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

**URL:** <https://hub.mender.io/t/adding-a-pre-configured-user-to-raspberry-pi-os-images-with-mender-convert/7922>\
**Category:** Mender-Convert\
**Created:** [July 28, 2025, 9:24am UTC](https://hub.mender.io/t/adding-a-pre-configured-user-to-raspberry-pi-os-images-with-mender-convert/7922 "2025-07-28T09:24:36Z")\
**Posts on this page:** 1\
**Page:** 1

<div class="post-metadata">

**Author:** ![TheYoctoJester](https://yyz2.discourse-cdn.com/flex036/user_avatar/hub.mender.io/theyoctojester/32/1444_2.png) [@TheYoctoJester](https://hub.mender.io/u/TheYoctoJester)\
**Post date:** [July 28, 2025, 9:24am UTC](https://hub.mender.io/t/adding-a-pre-configured-user-to-raspberry-pi-os-images-with-mender-convert/7922/1 "2025-07-28T09:24:36Z")

</div>

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:

```bash
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:

```bash
# 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`:

```bash
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