Skip to content
Daniel Gietmann
← Blog
Coding

Serving a remote SMB share locally without handing out the credentials

smb-proxy pulls a remote SMB share, for example from a Hetzner Storage Box, into a Docker container and serves it locally with its own login. How to start it, what it does inside the container, and the four places where you should be careful.

A Hetzner Storage Box speaks SMB in addition to SFTP, and almost every operating system can mount SMB shares. For every device that is supposed to use the box, though, you then need the box's credentials. From outside the Hetzner network, the box also has to have "External reachability" switched on.

smb-proxy is a small Docker container of mine that sits in between at this point. It logs in with the box's credentials and serves the share on your own network under its own user and password. The box's credentials stay in the container. This text refers to version 0.0.2, and the Storage Box serves as the example. With a different SMB server, only host, share and credentials change.

Starting

The image is on GHCR and is built for amd64 and arm64. For a Storage Box, starting it looks like this:

docker run -d \
  --name smb-proxy \
  --privileged \
  -p 127.0.0.1:1445:445 \
  -e SMB_HOST=u123456.your-storagebox.de \
  -e SMB_SHARE=backup \
  -e SMB_USER=u123456 \
  -e SMB_PASSWORD='Passwort-der-Box' \
  -e LOCAL_SHARE=proxy \
  -e LOCAL_USER=proxy \
  -e LOCAL_PASSWORD='lokales-Passwort' \
  ghcr.io/danielgtmn/smb-proxy:latest

The first four variables describe the box. At Hetzner, the share is called backup for the main user. For a sub-account, the share name is the sub-account's username, so for example u123456-sub1. Host and user then change along with it: SMB_HOST=u123456-sub1.your-storagebox.de and SMB_USER=u123456-sub1. SMB has to be enabled for the box in the Hetzner console, and after switching it on it can take a few minutes until it works. The three LOCAL_ variables define what the share is called on your own network and what your devices log in with.

After that you mount the share. On Linux this works with smbclient:

smbclient //127.0.0.1/proxy -p 1445 -U proxy

In the Finder you open the address smb://127.0.0.1:1445/proxy with Cmd+K. Port 1445 is in the example because port 445 is often already taken on a Mac.

What happens in the container

The container works through four steps:

  1. It reads the configuration from the environment variables. If SMB_HOST, SMB_SHARE, SMB_USER or SMB_PASSWORD is missing, it aborts immediately.
  2. It logs in to the box with the Go library go-smb2 and opens the share. If that fails, the container exits with the message "remote SMB verification failed". So when there are problems, a look at docker logs smb-proxy is worth it first.
  3. It mounts the share with mount -t cifs to /mnt/remote. The credentials are in a file with permissions 0600 and not on the command line.
  4. It writes an smb.conf, creates the local Samba user and starts smbd in the foreground. If smbd exits, the container exits too.

Mount options

As mount options, smb-proxy sets iocharset=utf8,rw,seal,vers=3.0,uid=0,gid=0,file_mode=0664,dir_mode=0775,noserverino by default. The important one is seal. According to the Hetzner documentation, SMB connections are not encrypted in every case, and encryption needs exactly this option.

According to Hetzner, cache=none can help when there are errors while copying files of 4 GB and up. The README says about this that SMB_MOUNT_OPTIONS takes "extra" options. In the code, however, the value replaces the entire default list. If you only set cache=none, you lose seal and vers=3.0. So write out the complete list and append the new option:

-e SMB_MOUNT_OPTIONS='iocharset=utf8,rw,seal,vers=3.0,uid=0,gid=0,file_mode=0664,dir_mode=0775,noserverino,cache=none'

Another default concerns IPv6. SMB_FORCE_IPV4 is set to true: the container resolves the hostname to an IPv4 address and passes it to the mount. That helps when Docker on a host prefers IPv6 that does not work there. With SMB_HOST_IP you set the address yourself.

TCP mode

Besides the gateway there is a second mode with SMB_PROXY_MODE=tcp. Then the container only forwards TCP connections from the local port to the SMB server:

docker run -d \
  --name smb-proxy \
  -p 127.0.0.1:1445:445 \
  -e SMB_PROXY_MODE=tcp \
  -e SMB_HOST=u123456.your-storagebox.de \
  ghcr.io/danielgtmn/smb-proxy:latest

Here every client logs in to the server itself, with the box's credentials. The TCP mode does not use the variables for user and password. In return, this mode does not need --privileged, because nothing is mounted. You use it when the clients have their own credentials and you only need a different route to the server.

What to watch out for

The container runs privileged

For the CIFS mount, the container needs elevated privileges. The README names --privileged or CAP_SYS_ADMIN. The bundled docker-compose.yml sets privileged: true, SYS_ADMIN and apparmor:unconfined together. A privileged container has far-reaching rights on the host. So only start it on a machine you trust anyway, and only with the image from this repository.

Without an address, the port listens on all network interfaces

A -p 1445:445 publishes the port on every interface of the host, and the bundled docker-compose.yml writes it exactly like that. Then every device on the same network can reach the share and log in with LOCAL_USER and LOCAL_PASSWORD. If only your machine needs the share, write -p 127.0.0.1:1445:445 as above, and in Compose accordingly "127.0.0.1:1445:445".

LOCAL_ALLOW_GUEST=true goes even further. Then nobody needs a password, and the share is configured as writable. Whoever reaches the port gets to the box's files. Leave the variable on false as long as you have not sealed off the port.

Passwords are in environment variables

All credentials go into the container through environment variables. Anyone who may run docker inspect smb-proxy on the host sees them in plain text. The README advises using Docker Secrets or a vault. The configuration only reads environment variables, though, and knows no variant that loads a password from a file. With Docker Compose you therefore put the values into a .env that does not belong in Git. In the repository, .env is listed in the .gitignore.

The local user has to exist in the container

The container does not create LOCAL_USER as a system user itself. It calls smbpasswd -a, and that requires a user that already exists in the system. The default value proxy works because Debian ships a system user with that name. With a different name such as daniel, startup fails according to the Samba documentation, and the log says "create local samba user".

This user is also the one Samba uses to access the files. With the default options, though, the mount belongs to root (uid=0,gid=0), files have 0664, folders 0775. For proxy that presumably leaves only reading, even though the share is entered in the smb.conf with read only = no. After starting, check once whether you can create a file.

What it is enough for

smb-proxy holds exactly one share per container. For two boxes or two shares you start two containers with different host ports. It is a small helper for home or a small network where the box's credentials are supposed to live in one place.

If you would rather have the box in the Finder on the Mac without Docker, you will find the route via SFTP in this post. Questions and bugs about smb-proxy belong in the issues on GitHub.

Common questions

How do I use a Hetzner Storage Box over SMB without storing the credentials on every device?
With smb-proxy. The Docker container logs in with the box's credentials and serves the share on your own network with its own user and password, which you set through LOCAL_USER and LOCAL_PASSWORD. The box's credentials stay in the container.
Why does smb-proxy need --privileged?
For the CIFS mount, the smb-proxy container needs elevated privileges, and the README names --privileged or CAP_SYS_ADMIN. A privileged container has far-reaching rights on the host, so only start it on a machine you trust anyway. The TCP mode with SMB_PROXY_MODE=tcp does not need --privileged, because nothing is mounted.
What happens when I set SMB_MOUNT_OPTIONS in smb-proxy?
The value of SMB_MOUNT_OPTIONS replaces the entire default list of smb-proxy's mount options. If you only set cache=none, you lose seal and vers=3.0, and seal is the option for encryption. So write out the complete list and append the new option.
How do I prevent every device on the network from reaching the smb-proxy share?
Publish the port only on your own machine, so -p 127.0.0.1:1445:445 instead of -p 1445:445. Without an address, the port listens on every interface of the host. You leave LOCAL_ALLOW_GUEST on false as long as you have not sealed off the port.