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.5.0
passwd:
  users:
    - name: jlebon
    - name: miabbott

You will typically want to configure SSH keys or a password, in order to be able to log in 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.5.0
passwd:
  users:
    - name: core
      ssh_authorized_keys:
        - ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQDHn2eh...
    - name: jlebon
      ssh_authorized_keys:
        - ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABgQDC5QFS...
        - ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIIveEaMRW...
    - name: miabbott
      ssh_authorized_keys:
        - ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAACAQDTey7R...

Using File References to SSH Keys

Depending on the configuration variant and version you use, you can use local file references to SSH public keys instead of inlining them. The example from the previous section can thus be rewritten as follows:

variant: fcos
version: 1.5.0
passwd:
  users:
    - name: core
      ssh_authorized_keys_local:
        - users/core/id_rsa.pub
    - name: jlebon
      ssh_authorized_keys_local:
        - users/jlebon/id_rsa.pub
        - users/jlebon/id_ed25519.pub
    - name: miabbott
      ssh_authorized_keys_local:
        - users/miabbott/id_rsa.pub

You have to use butane with the --files-dir parameter to allow loading files from disk when converting to Ignition configurations for this to work.

Check the Configuration specifications for more details and which versions of your selected variant support it. Generally, each file may contain multiple SSH keys, one per line, and you may additionally specify inline ssh_authorized_keys as well as long as the SSH keys are unique.

SSH Key Locations

sshd uses a helper program, specified via the AuthorizedKeysCommand directive, to read public keys from files in a user’s ~/.ssh/authorized_keys.d directory. The AuthorizedKeysCommand is tried after the usual AuthorizedKeysFile files (defaulting to ~/.ssh/authorized_keys) and will not be executed if a matching key is found there. Key files in ~/.ssh/authorized_keys.d are read in alphabetical order, ignoring dotfiles.

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.

To debug the reading of ~/.ssh/authorized_keys.d, manually run the helper program and inspect its output:

/usr/libexec/ssh-key-dir

To view and validate the effective configuration for sshd, two test modes (-t, -T) are available as documented on the manual pages.

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.5.0
passwd:
  users:
    - name: core
      ssh_authorized_keys:
        - ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQDHn2eh...
    - name: jlebon
      ssh_authorized_keys:
        - ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABgQDC5QFS...
        - ssh-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.5.0
passwd:
  users:
    - name: core
      ssh_authorized_keys:
        - ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQDHn2eh...
    - name: jlebon
      groups:
        - wheel
      ssh_authorized_keys:
        - ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABgQDC5QFS...
        - ssh-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.5.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...
        - ssh-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.5.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...
        - ssh-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.5.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 ›