Adding a Pre-configured User to Raspberry Pi OS Images with mender-convert

Tutorials Mender-Convert
1

Raspberry Pi OS images by default run a first-boot wizard which prompts for user creation. This tutorial demonstrates how to bypass this process by pre-configuring a user during image conversion with mender-convert.

Prerequisites

  • mender-convert repository cloned and Docker image built
  • Raspberry Pi OS image file available
  • Basic understanding of mender-convert configuration

Creating the Configuration Fragment

The Raspberry Pi OS uses userconf.txt in the boot partition to configure users on first boot. We’ll create a configuration fragment that writes this file during the conversion process.

Create a new configuration file:

cat > input/user_config << 'EOF'
# Configuration to create a pre-configured user
# This writes userconf.txt directly to the boot partition during conversion

function create_default_user() {
log_warn "Creating default user mender:mender via userconf.txt"

# Create userconf.txt in boot partition
# Format: username:encrypted_password
echo 'mender:$6$4ISZtBHbmvfYRSpL$.s54rsUJ7rH/JvknKEt6NcOOXLX4/WORtvYsh3uaIfZ1BhqqxGvnJCVF7MHUzQaTGdmw4VHAGBSHrwCojbOlp0' > work/boot/userconf.txt
}

PLATFORM_MODIFY_HOOKS+=(create_default_user)
EOF

Understanding the Configuration

The configuration fragment:

  • Defines a function create_default_user that runs during the modify phase
  • Creates userconf.txt in the boot partition work directory
  • Uses the format username:encrypted_password required by Raspberry Pi OS
  • Registers the function as a platform modification hook

The password hash shown creates the user mender with password mender. To generate your own:

# Using mkpasswd (whois package)
mkpasswd -m sha-512 yourpassword

# Or using openssl
openssl passwd -6 yourpassword

Running the Conversion

Include the configuration fragment when running mender-convert:

MENDER_ARTIFACT_NAME=release-1 ./docker-mender-convert \
--disk-image input/images/2025-05-13-raspios-bookworm-arm64-lite.img \
--config configs/raspberrypi/uboot/debian/raspberrypi4_bookworm_64bit_config \
--overlay input/rootfs_overlay_hosted \
--config input/user_config

Notes

  • This approach works with Raspberry Pi OS Bookworm and later releases
  • The userconf.txt file is consumed and removed on first boot
  • For production use, consider stronger passwords and secure hash generation
  • The boot partition location differs between OS versions (/boot vs /boot/firmware)

Troubleshooting

If login fails after conversion:

  1. Verify the password hash is correctly formatted
  2. Ensure no spaces or extra characters in userconf.txt
  3. Check that the file is in the actual boot partition, not /boot in rootfs
  4. Consider SSH may be disabled by default - enable with touch work/boot/ssh in the configuration