Creating A User

Garden Linux installations do not create a default user on installation. This is due to the specific use cases it was designed for not requiring a user.

Automate Provisioning

For automated user creation and system configuration, use:

• cloud-init for cloud platforms (AWS, Azure, GCP, OpenStack)
• Ignition for bare-metal and PXE deployments

These tools configure users, SSH keys, files, and services on first boot without manual intervention.

If you would still like to create a new user account manually, follow the instructions below.

When Is Manual User Creation Required?

Manual user creation is necessary when automated provisioning tools are unavailable:

• Deploying on bare metal without PXE/Ignition support
• Running on KVM/QEMU without cloud-init (e.g., for testing)
• Any environment where cloud-init or Ignition provisioning is unavailable

For automated provisioning:

• Cloud platforms — Use cloud-init (see platform-specific tutorials below)
• PXE/bare-metal — Use Ignition with PXE boot

Platform-specific tutorials:

• First Boot on AWS
• First Boot on Azure
• First Boot on GCP
• First Boot on OpenStack

Method 1: chroot (For Bare Metal / Offline Deployments)

Use this method when you have direct access to the disk (e.g., from a live system before first boot).

Step 1: Mount the Root Partition

# Identify and mount the root partition
TARGET_DISK="/dev/sda" # Or your desired target drive
ROOT_PART="${TARGET_DISK}3" # Partition 3 on gardener builds
USR_PART="${TARGET_DISK}1"  # Partition 1 contains usr/

mount ${ROOT_PART} /mnt
mount -o ro ${USR_PART} /mnt/usr

Step 2: Create the User

USERNAME="gardenlinux"
chroot /mnt /bin/bash -c "useradd -m -G wheel -s /bin/bash ${USERNAME}"

Step 3: Unmount and Reboot

Finally, you need to unmount the image and reboot the system without any live media present.

umount /mnt/usr
umount /mnt
reboot

For a complete walkthrough and to learn what else you can do with a local installation, see the First Boot on Bare Metal guide.

Method 2: fw_cfg script (KVM/QEMU)

Use this method when launching Garden Linux in QEMU/KVM. This script executes automatically on first boot.

USERNAME="gardenlinux"
SSH_PUBLIC_KEY="ssh-ed25519 AAAA... user@host"

cat > fw_cfg-script.sh <<EOF
#!/usr/bin/env bash
set -eufo pipefail
# Create user with sudo access
useradd -U -m -G wheel -s /bin/bash ${USERNAME}
# Configure SSH
mkdir -p /home/${USERNAME}/.ssh
chmod 700 /home/${USERNAME}/.ssh
echo "${SSH_PUBLIC_KEY}" >> /home/${USERNAME}/.ssh/authorized_keys
chown -R ${USERNAME}:${USERNAME} /home/${USERNAME}/.ssh
chmod 600 /home/${USERNAME}/.ssh/authorized_keys
# Enable SSH service
systemctl enable --now ssh
EOF

Pass this script to QEMU using:

qemu-system-x86_64 ... \
    -fw_cfg name=opt/gardenlinux/config_script,file=fw_cfg-script.sh

For a complete walkthrough and more information about setting up Garden Linux on KVM see First Boot on KVM.

Method 3: cloud-init user-data (Cloud Platforms)

On cloud platforms with cloud-init support, users are typically pre-configured. You only need to enable SSH to access them:

cat > user_data.sh <<EOF
#!/usr/bin/env bash
systemctl enable --now ssh
EOF

For complete cloud-init provisioning examples including custom user creation, package installation, and file configuration, see the Provision with cloud-init guide.

For default usernames per platform, see Provision with cloud-init — Default Usernames.

The Wheel Group

Garden Linux uses the wheel group for passwordless sudo access. Users in this group have full administrative access without requiring a password for sudo commands.

You can verify if the user is correctly added to this group by running:

groups ${USERNAME}

Which should produce this output:

$USERNAME : wheel

Setting a Password (optional)

Garden Linux is configured for SSH key-based authentication by default. If you need password authentication (which is not recommended for any production environment) you can do so:

# Set a password for the user account
chroot /mnt /bin/bash -c "passwd ${USERNAME}"

# Or on a running system
sudo passwd ${USERNAME}

Security Warning Password authentication is disabled by default in

Garden Linux' SSH configuration for security reasons. We strongly recommend key-based authentication on any networked system, even in a testing context. :::