unraid-smb-password-portal

unraid-smb-password-portal

Docker app from bmartino1's Repository

Non-admin website for admins to direct end-users for there account password change.

Requirements

run as unraid network host, connect to samba via localhost for security
Overview
Non-admin website for admins to direct end-users for there account password change. An end user can then non-admin change of there share network passwords... Simple web UI for changing an SMB password Users enter: SMB username current SMB password new SMB password confirmation password Uses Samba's smbpasswd client command Talks to the Unraid host Samba service Reads Unraid SMB users from /boot/config/smbpasswd Excludes root from the client portal by default Does not expose plaintext passwords Does not require Docker socket access Does not need Unraid root credentials Auto-generates a persistent Flask secret key on first start Optional debug endpoint for testing user detection Intended for LAN, VPN, Tailscale, WireGuard, or reverse-proxy-protected use

Unraid SMB Password Portal

Docker Hub GitHub Unraid

Unraid SMB Password Portal

A small self-service web portal for Unraid SMB users to change their own Samba password without needing access to the Unraid administration interface.

This container is designed specifically for Unraid. It provides a simple browser-based front end and uses Samba's standard smbpasswd client to send the password change to the Samba service running on the Unraid host.

The user must know their current SMB password before it can be changed. This is a password-change portal, not an administrator password-reset tool.

Unraid only: this image expects the Unraid SMB configuration layout and is intended to run alongside the Samba service provided by Unraid.

Links

What It Does

The portal gives an existing Unraid SMB user a simple page where they can enter:

  • their SMB username
  • their current SMB password
  • a new SMB password
  • confirmation of the new password

After the form is validated, the application runs Samba's smbpasswd client against the Unraid host. The old and new passwords are supplied to smbpasswd through standard input rather than being placed on the command line.

The application does not directly edit Unraid's Samba password database and does not require the Docker socket or Unraid root credentials.

Features

  • Browser-based SMB password changes for non-admin users
  • Uses the existing Unraid Samba service
  • Requires the user's current SMB password
  • Reads the Unraid SMB user list from /boot/config/smbpasswd
  • Excludes the root account from the SMB user portal
  • Optional typed username or detected-user dropdown
  • Configurable minimum password length
  • CSRF protection for the password-change form
  • Basic per-user/IP in-memory rate limiting
  • Persistent Flask session secret stored in appdata
  • Health-check endpoint
  • Optional SMB user-detection debug endpoint
  • No Docker socket access required
  • No Unraid administrator credentials required

Recommended Unraid Installation

The easiest installation is through the Unraid Community Applications template.

The normal configuration uses Host networking so the container can contact the Unraid Samba service at 127.0.0.1.

Typical settings:

Network Type: Host
WebUI: http://UNRAID-IP:8099

SAMBA_SERVER=127.0.0.1
MIN_PASSWORD_LENGTH=8
SHOW_USER_DROPDOWN=0
ENABLE_DEBUG_USERS=0

/config        -> /mnt/user/appdata/smb-password-portal/config
/unraid-config -> /boot/config (read-only)

The /boot/config mount is read-only. It is used to identify the SMB users configured on the Unraid server.

Manual Docker Run

If you prefer to create the container manually:

mkdir -p /mnt/user/appdata/smb-password-portal/config

docker run -d \
  --name smb-password-portal \
  --network=host \
  --restart unless-stopped \
  -e SAMBA_SERVER="127.0.0.1" \
  -e MIN_PASSWORD_LENGTH="8" \
  -e SHOW_USER_DROPDOWN="0" \
  -e ENABLE_DEBUG_USERS="0" \
  -v /mnt/user/appdata/smb-password-portal/config:/config \
  -v /boot/config:/unraid-config:ro \
  bmmbmm01/unraid-smb-password-portal:latest

Then open:

http://UNRAID-IP:8099

How the Password Change Works

For a submitted username, the application calls:

smbpasswd -s -r 127.0.0.1 -U username

The user's current password and new password are passed to that process through stdin.

The portal first reads the available SMB usernames from:

/boot/config/smbpasswd

which is normally mounted inside the container as:

/unraid-config/smbpasswd

If the SMB password file is unavailable or contains no usable users, the application can fall back to the Unraid passwd file while filtering system/service accounts.

Configuration

Variable Default Description
SAMBA_SERVER 127.0.0.1 Samba server contacted by smbpasswd. Host networking on Unraid should normally use 127.0.0.1.
MIN_PASSWORD_LENGTH 8 Minimum length accepted for a new SMB password.
SHOW_USER_DROPDOWN 0 0 lets the user type their username. 1 displays detected SMB usernames in a dropdown.
ENABLE_DEBUG_USERS 0 Enables /debug/users for troubleshooting user detection. Leave disabled for normal use.
MAX_ATTEMPTS 5 Number of password-change attempts allowed within the rate-limit window for a user/IP combination.
RATE_WINDOW_SECONDS 300 In-memory rate-limit window in seconds.
SECRET_KEY generated Optional Flask session secret. Normally generated automatically and persisted under /config.
UNRAID_CONFIG_DIR /unraid-config Container path for the read-only Unraid configuration mount.
SMBPASSWD_BIN /usr/bin/smbpasswd Path to the Samba smbpasswd client inside the container.

Username Entry vs. Dropdown

The recommended setting is:

SHOW_USER_DROPDOWN=0

Users type their existing SMB username instead of being shown a list of accounts configured on the server.

Set it to 1 if you prefer a dropdown populated from the detected Unraid SMB users.

Security and Scope

This application is intentionally limited: it gives an existing SMB user a way to change their own password using their current credentials.

It does not:

  • create Samba users
  • reset a forgotten password
  • provide Unraid administrator access
  • require the Unraid root password
  • mount the Docker socket
  • directly write to /boot/config/smbpasswd

Passwords submitted through the form are passed to the Samba client for the password-change operation. The application does not maintain its own password database.

Because this is an account-management page, keep the WebUI available only to people who should be able to reach your Unraid services. If you make the page available outside your local network, use an appropriately secured access method and HTTPS.

Persistent Session Key

You normally do not need to configure SECRET_KEY.

On first start, the entrypoint generates a random Flask secret and saves it to:

/config/secret_key

With the normal Unraid appdata mapping, that file survives container updates and restarts so browser sessions and form tokens remain consistent.

Health Check

Check the application locally from the Unraid host:

curl http://127.0.0.1:8099/healthz

Expected response:

ok

Container logs can be viewed with:

docker logs -n 100 smb-password-portal

Troubleshooting SMB User Detection

The debug endpoint is disabled by default.

Temporarily set:

ENABLE_DEBUG_USERS=1

Then check:

curl http://127.0.0.1:8099/debug/users

Example:

source=smbpasswd
count=2
user1
user2

Return ENABLE_DEBUG_USERS to 0 after troubleshooting.

You can also verify the read-only Unraid configuration mount:

docker exec -it smb-password-portal sh
ls -lah /unraid-config
cut -d: -f1 /unraid-config/smbpasswd

Testing a Password Change

A successful portal message means smbpasswd returned successfully. You can independently test the new SMB credentials from the Unraid host with smbclient:

USERNAME='username'
NEWPASS='your_new_password'

smbclient -L //127.0.0.1 -U "${USERNAME}%${NEWPASS}"

If authentication succeeds, Samba should return the shares visible to that account.

Bridge Networking

Host networking is the intended Unraid setup, but bridge networking can be used if needed.

One approach is to map port 8099, add the Docker host gateway, and point SAMBA_SERVER at it:

docker run -d \
  --name smb-password-portal \
  --restart unless-stopped \
  -p 8099:8099 \
  --add-host=host.docker.internal:host-gateway \
  -e SAMBA_SERVER="host.docker.internal" \
  -e MIN_PASSWORD_LENGTH="8" \
  -e SHOW_USER_DROPDOWN="0" \
  -e ENABLE_DEBUG_USERS="0" \
  -v /mnt/user/appdata/smb-password-portal/config:/config \
  -v /boot/config:/unraid-config:ro \
  bmmbmm01/unraid-smb-password-portal:latest

For the standard Unraid Community Applications installation, use the Host network configuration supplied by the template.

Common Problems

Invalid form token

If you see:

Invalid form token. Refresh the page and try again.

Refresh the page and submit the form again. This can happen when an older form remains open across a container restart or session-key change.

If it continues, clear the browser data for the portal or try a private/incognito window.

Username is not listed as an SMB user

Confirm that the user exists in Unraid's SMB password file:

cut -d: -f1 /boot/config/smbpasswd

Also verify that /boot/config is mounted read-only to /unraid-config inside the container.

Password change fails

Confirm the user is entering the current SMB password, not an unrelated Unraid web login password.

Check the container logs:

docker logs -n 100 smb-password-portal

For the normal Host network setup, SAMBA_SERVER should be:

127.0.0.1

Web page does not open

Check that the container is running:

docker ps | grep smb-password-portal

Then check the health endpoint:

curl http://127.0.0.1:8099/healthz

License

This project is released under the MIT License.

The container includes Samba client utilities provided by the Samba project; those components remain subject to their respective upstream licenses.

Categories

Download Statistics

3,118
Total Downloads

Related apps

Explore more like this

Explore all

Links

Details

Repository
bmmbmm01/unraid-smb-password-portal:latest
Last Updated2026-05-20
First Seen2026-05-20

Runtime arguments

Web UI
http://[IP]:[PORT:8099]
Network
host
Shell
sh
Privileged
false
Extra Params
--restart unless-stopped

Template configuration

SAMBA_SERVERVariable

The Samba IP of the Unraid Machine to list and change users

Default
127.0.0.1
Value
127.0.0.1
MIN_PASSWORD_LENGTHVariable

Min new password length

Default
12
Value
8
SHOW_USER_DROPDOWNVariable

0 users enter password 1 drop down shows samba all users

Default
1
Value
0
ENABLE_DEBUG_USERSVariable

Curl debug check samba list users curl http://127.0.0.1:8099/debug/users

Default
1
Value
0
AppdataPathrw

appdata website SECRET_KEY file for python flask

Target
/config
Default
/mnt/user/appdata/smb-password-portal/config
Value
/mnt/user/appdata/smb-password-portal/config
Unraid SMB StuffPathro
Target
/unraid-config
Default
/boot/config
Value
/boot/config