# How to Configure WebUI Basic Authentication in AtomCam Tools

> Learn to configure WebUI basic authentication in AtomCam Tools using hack.ini and mod_auth. Protect your settings with an account and password. Simple setup with clear instructions.

- Repository: [Mitsuru Nakada/atomcam_tools](https://github.com/mnakada/atomcam_tools)
- Tags: how-to-guide
- Published: 2026-03-07

---

**AtomCam Tools implements WebUI basic authentication using lighttpd's `mod_auth` module with an MD5 digest stored in [`hack.ini`](https://github.com/mnakada/atomcam_tools/blob/main/hack.ini), enabling password protection through a simple toggle in the Settings page.**

The open-source AtomCam Tools firmware provides a comprehensive Web interface for managing AtomCam devices. For users requiring access control, the project implements standard HTTP basic authentication through lighttpd, configured via the Vue.js-based settings panel and propagated through shell scripts that manage the underlying web server configuration.

## How WebUI Basic Authentication Works

The authentication system follows a three-stage pipeline: UI capture, digest generation, and lighttpd enforcement. When you enable the **Login Authentication** toggle in the device settings, the Vue frontend captures your chosen account name and password, computes an MD5 digest in the format `user:realm:md5(user:realm:password)`, and stores this value in the `DIGEST` configuration field.

The [`overlay_rootfs/scripts/lighttpd.sh`](https://github.com/mnakada/atomcam_tools/blob/main/overlay_rootfs/scripts/lighttpd.sh) script then reads this digest from [`/tmp/hack.ini`](https://github.com/mnakada/atomcam_tools/blob/main//tmp/hack.ini) at startup. If `DIGEST` contains a value, the script writes it to `/etc/lighttpd/user.digest` and enables the `mod_auth` module; if empty, authentication remains disabled. All subsequent HTTP requests to the Web UI require valid credentials matching the stored digest.

## Configuring Authentication via the Web Interface

The primary method for enabling WebUI basic authentication uses the Settings page components defined in [`web/source/vue/Setting.vue`](https://github.com/mnakada/atomcam_tools/blob/main/web/source/vue/Setting.vue).

### Enabling the Login Toggle

Navigate to the device settings and locate the **Login Authentication** switch (`loginAuth`). When activated, the interface conditionally renders two additional input fields for your account name and password:

```html
<!-- Setting.vue template structure (lines 329-331) -->
<SettingSwitch i18n="deviceSettings.loginAuthentication" v-model="loginAuth" />
<SettingInput v-if="loginAuth==='on'" i18n="deviceSettings.account" type="text" v-model="account" />
<SettingInput v-if="loginAuth==='on'" i18n="deviceSettings.password" type="password" v-model="password" />

```

Toggle the switch to **on**, enter your desired credentials, and click **Save** to propagate the changes.

### Persisting the Configuration

On save, the application invokes [`set_icamera_config.sh`](https://github.com/mnakada/atomcam_tools/blob/main/set_icamera_config.sh) (via CGI) to write the configuration back to [`/tmp/hack.ini`](https://github.com/mnakada/atomcam_tools/blob/main//tmp/hack.ini). The full configuration object, including the generated `DIGEST` string, is persisted to the device's filesystem, ensuring authentication settings survive reboots.

## The Digest Generation Process

When you save settings with authentication enabled, the Vue component computes a standard HTTP digest authentication hash. Located at lines 1270-1273 in [`web/source/vue/Setting.vue`](https://github.com/mnakada/atomcam_tools/blob/main/web/source/vue/Setting.vue), the logic verifies that `loginAuth` is active and the account field is non-empty before generating the credential string:

```javascript
// Digest generation logic (simplified from Setting.vue)
if ((this.loginAuth === 'on') && this.account.length) {
  // Default realm is "atomcam" (stored in this.relm)
  this.config.DIGEST = `${this.account}:${this.relm}:` +
                      md5(`${this.account}:${this.relm}:${this.password}`);
}

```

The resulting `DIGEST` value follows the format `username:realm:md5_hash`, where the MD5 hash is computed over the string `username:realm:password`. This format complies with lighttpd's `mod_auth` digest authentication requirements.

## lighttpd Configuration and Enforcement

The web server configuration is managed by [`overlay_rootfs/scripts/lighttpd.sh`](https://github.com/mnakada/atomcam_tools/blob/main/overlay_rootfs/scripts/lighttpd.sh), which executes during system startup or when the lighttpd service restarts. This script reads the `DIGEST` value from [`hack.ini`](https://github.com/mnakada/atomcam_tools/blob/main/hack.ini) and conditionally enables authentication:

```bash
#!/bin/sh
HACK_INI=/tmp/hack.ini
DIGEST=$(awk -F "=" '/^DIGEST *=/ {print $2}' $HACK_INI)

if [ "$DIGEST" != "" ]; then
  echo $DIGEST > /etc/lighttpd/user.digest
  echo 'server.modules += ( "mod_auth" )' > /etc/lighttpd/auth.conf
else
  echo $DIGEST > /etc/lighttpd/user.digest
  echo '#server.modules += ( "mod_auth" )' > /etc/lighttpd/auth.conf
fi

```

When `DIGEST` is non-empty, the script:
1. Writes the digest to `/etc/lighttpd/user.digest`
2. Enables `mod_auth` by writing an active configuration line to [`/etc/lighttpd/auth.conf`](https://github.com/mnakada/atomcam_tools/blob/main//etc/lighttpd/auth.conf)

If authentication is disabled (empty `DIGEST`), lighttpd runs with authentication modules commented out, allowing unrestricted access to the Web UI and CGI endpoints.

## Manual Configuration via hack.ini

For advanced users or recovery scenarios, you can bypass the Web interface and edit [`/tmp/hack.ini`](https://github.com/mnakada/atomcam_tools/blob/main//tmp/hack.ini) directly. Add or modify the `DIGEST` line using the format:

```ini

# /tmp/hack.ini

DIGEST=alice:atomcam:5f4dcc3b5aa765d61d8327deb882cf99

```

In this example, `alice` is the account name, `atomcam` is the realm, and `5f4dcc3b5aa765d61d8327deb882cf99` is the MD5 hash of `alice:atomcam:password`. After editing, apply the configuration by running:

```bash
/scripts/lighttpd.sh restart

```

Alternatively, reboot the device to trigger the initialization scripts that read [`hack.ini`](https://github.com/mnakada/atomcam_tools/blob/main/hack.ini) and configure lighttpd accordingly.

## Summary

- **WebUI basic authentication** in AtomCam Tools relies on lighttpd's `mod_auth` module and MD5 digest files.
- Enable protection via the **Login Authentication** toggle in [`web/source/vue/Setting.vue`](https://github.com/mnakada/atomcam_tools/blob/main/web/source/vue/Setting.vue), which reveals account and password fields.
- The system generates a `DIGEST` value in `user:realm:md5(user:realm:password)` format, stored in [`/tmp/hack.ini`](https://github.com/mnakada/atomcam_tools/blob/main//tmp/hack.ini).
- [`overlay_rootfs/scripts/lighttpd.sh`](https://github.com/mnakada/atomcam_tools/blob/main/overlay_rootfs/scripts/lighttpd.sh) (lines 13-20) reads this digest, writes it to `/etc/lighttpd/user.digest`, and toggles the authentication module.
- Manual configuration is possible by editing the `DIGEST` field in [`hack.ini`](https://github.com/mnakada/atomcam_tools/blob/main/hack.ini) and restarting the lighttpd service.

## Frequently Asked Questions

### What format does the DIGEST field use?

The `DIGEST` field uses lighttpd's digest authentication format: `username:realm:md5_hash`. The MD5 hash is computed over the string `username:realm:password`. For example, the account "admin" with password "secret" in the "atomcam" realm produces a digest of `admin:atomcam: followed by the MD5 hash of "admin:atomcam:secret".

### How do I disable WebUI basic authentication once enabled?

To disable authentication, toggle the **Login Authentication** switch to **off** in the Settings page and save, or manually edit [`/tmp/hack.ini`](https://github.com/mnakada/atomcam_tools/blob/main//tmp/hack.ini) to set `DIGEST=` (empty value). Then run `/scripts/lighttpd.sh restart` to apply the changes. When the digest is empty, the script comments out the `mod_auth` module in lighttpd's configuration.

### Can I change the authentication realm from "atomcam"?

The realm is hardcoded to "atomcam" in the current implementation within [`web/source/vue/Setting.vue`](https://github.com/mnakada/atomcam_tools/blob/main/web/source/vue/Setting.vue). While the JavaScript references `this.relm` (likely a typo for realm), the default and expected value is "atomcam". Changing this would require modifying the source code and regenerating the Web UI components.

### What happens if I forget the WebUI password?

If you forget the password, you must access the device via SSH or serial console and manually edit [`/tmp/hack.ini`](https://github.com/mnakada/atomcam_tools/blob/main//tmp/hack.ini) to either clear the `DIGEST` field (disable authentication) or set a new digest with a known password. Because the stored value is a one-way MD5 hash, the original password cannot be recovered from the configuration file.