Configuring Users

Default User

By default, a privileged user named core is created on the Fedora CoreOS system, but it is not configured with a default password or SSH key. If you wish to use the core user, you must provide an Ignition config which includes a password and/or SSH key(s) for the core user. Alternatively you may create additional, new users via Ignition configs.

If you do not want to use Ignition to manage the default user’s SSH key(s), you can make use of the Afterburn support and provide an SSH key via your cloud provider.

Creating a New User

To create a new user (or users), add it to the users list of your Butane config. In the following example, the config creates two new usernames, but doesn’t configure them to be especially useful.

variant: fcos
version: 1.4.0
passwd:
  users:
    - name: jlebon
    - name: miabbott

You will typically want to configure SSH keys or a password, in order to be able to login as those users.

Using an SSH Key

To configure an SSH key for a local user, you can use a Butane config:

variant: fcos
version: 1.4.0
passwd:
  users:
    - name: core
      ssh_authorized_keys:
        - ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQDHn2eh...
    - name: jlebon
      ssh_authorized_keys:
        - ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABgQDC5QFS...
        - sh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIIveEaMRW...
    - name: miabbott
      ssh_authorized_keys:
        - ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAACAQDTey7R...

SSH Key Locations

sshd uses a helper program to read public keys from files in a user’s ~/.ssh/authorized_keys.d directory. Key files are read in alphabetical order, ignoring dotfiles. The standard ~/.ssh/authorized_keys file is read afterward, in the usual way. To debug the reading of ~/.ssh/authorized_keys.d, manually run the helper program and inspect its output:

/usr/libexec/ssh-key-dir

Ignition writes configured SSH keys to ~/.ssh/authorized_keys.d/ignition. On platforms where SSH keys can be configured at the platform level, such as AWS, Afterburn writes those keys to ~/.ssh/authorized_keys.d/afterburn.

Using Password Authentication

Fedora CoreOS ships with no default passwords. You can use a Butane config to set a password for a local user. Building on the previous example, we can configure the password_hash for one or more users:

variant: fcos
version: 1.4.0
passwd:
  users:
    - name: core
      ssh_authorized_keys:
        - ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQDHn2eh...
    - name: jlebon
      ssh_authorized_keys:
        - ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABgQDC5QFS...
        - sh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIIveEaMRW...
    - name: miabbott
      password_hash: $y$j9T$aUmgEDoFIDPhGxEe2FUjc/$C5A...
      ssh_authorized_keys:
        - ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAACAQDTey7R...

To generate a secure password hash, use mkpasswd from the whois package. Your Linux distro may ship a different mkpasswd implementation; you can ensure you’re using the correct one by running it from a container:

$ podman run -ti --rm quay.io/coreos/mkpasswd --method=yescrypt
Password:
$y$j9T$A0Y3wwVOKP69S.1K/zYGN.$S596l11UGH3XjN...

The yescrypt hashing method is recommended for new passwords. For more details on hashing methods, see man 5 crypt.

The configured password will be accepted for local authentication at the console. By default, Fedora CoreOS does not allow password authentication via SSH.

Configuring Groups

Fedora CoreOS comes with a few groups configured by default: root, adm, wheel, sudo, systemd-journal, docker

When configuring users via Butane configs, we can specify groups that the user(s) should be a part of.

variant: fcos
version: 1.4.0
passwd:
  users:
    - name: core
      ssh_authorized_keys:
        - ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQDHn2eh...
    - name: jlebon
      groups:
        - wheel
      ssh_authorized_keys:
        - ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABgQDC5QFS...
        - sh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIIveEaMRW...
    - name: miabbott
      groups:
        - docker
        - wheel
      password_hash: $y$j9T$aUmgEDoFIDPhGxEe2FUjc/$C5A...
      ssh_authorized_keys:
        - ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAACAQDTey7R...

If a group does not exist, users should create them as part of the Butane config.

variant: fcos
version: 1.4.0
passwd:
  groups:
    - name: engineering
    - name: marketing
      gid: 9000
  users:
    - name: core
      ssh_authorized_keys:
        - ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQDHn2eh...
    - name: jlebon
      groups:
        - engineering
        - wheel
      ssh_authorized_keys:
        - ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABgQDC5QFS...
        - sh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIIveEaMRW...
    - name: miabbott
      groups:
        - docker
        - marketing
        - wheel
      password_hash: $y$j9T$aUmgEDoFIDPhGxEe2FUjc/$C5A...
      ssh_authorized_keys:
        - ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAACAQDTey7R...

Configuring Administrative Privileges

The easiest way for users to be granted administrative privileges is to have them added to the sudo and wheel groups as part of the Butane config.

variant: fcos
version: 1.4.0
passwd:
  groups:
    - name: engineering
    - name: marketing
      gid: 9000
  users:
    - name: core
      ssh_authorized_keys:
        - ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQDHn2eh...
    - name: jlebon
      groups:
        - engineering
        - wheel
        - sudo
      ssh_authorized_keys:
        - ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABgQDC5QFS...
        - sh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIIveEaMRW...
    - name: miabbott
      groups:
        - docker
        - marketing
        - wheel
        - sudo
      password_hash: $y$j9T$aUmgEDoFIDPhGxEe2FUjc/$C5A...
      ssh_authorized_keys:
        - ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAACAQDTey7R...

Enabling SSH Password Authentication

To enable password authentication via SSH, add the following to your Butane config:

variant: fcos
version: 1.4.0
storage:
  files:
    - path: /etc/ssh/sshd_config.d/20-enable-passwords.conf
      mode: 0644
      contents:
        inline: |
          # Fedora CoreOS disables SSH password login by default.
          # Enable it.
          # This file must sort before 40-disable-passwords.conf.
          PasswordAuthentication yes

Want to help? Learn how to contribute to Fedora Docs ›