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:
- Verify the password hash is correctly formatted
- Ensure no spaces or extra characters in
userconf.txt
- Check that the file is in the actual boot partition, not
/boot
in rootfs - Consider SSH may be disabled by default - enable with
touch work/boot/ssh
in the configuration