User Management

With the introduction of the web configuration interface, OpenWebRX 1.0 also received a user database to be able to manage access to that interface. So, in order to be able to access the web configuration interface, you must create a user.

For security reasons, there is no default user and password in any of the installation methods, so this step is mandatory.

Managing users is currently done on the command line only, so the first step is to gain access to a shell on your receiver via keyboard and mouse, SSH, VNC or similar method.

The commands to manage your users are typically called through the openwebrx tool, which is available on all packaged installations (including the RPi images). Manual installations can run the same commands through the openwebrx.py file that is in the root of the source tree. Docker installations can run the command, too, but it is somewhat cumbersome to get to, so a dedicated initialization method is available in the docker images.

Available commands

openwebrx admin adduser [username]            Add a new user
openwebrx admin removeuser [username]         Remove an existing user
openwebrx admin resetpassword [username]      Reset a user's password
openwebrx admin disableuser [username]        Disable a user
openwebrx admin enableuser [username]         Enable a user
openwebrx admin listusers                     List enabled users
openwebrx admin hasuser                       Test if a user exists

Most commands require you to pass a [username] to be able to perform their respective tasks.

Note: The square brackets [] denote a replacement syntax, they are not part of the actual command. Do not copy the square brackets (unless you want them to become part of the username).

Note: Depending on your setup, you may need to run these commands with elevated permissions, otherwise you will receive errors about files not being writable. Please check your distribution's documentation on this topic. Most distributions use sudo for this purpose.

There is currently no additional authorization method in place, so all users that are currently active will be able to access the web configuration interface.

A note about files and permissions

The following information is particularly important for manual installations. Systems installed from the package repository (including RPi images) will have these permissions set up accordingly during their setup, so this information is provided in case you need or want to make customizations. Docker setups may need to restrict access to their volume storage, if necessary.

The user database itself is stored in /var/lib/openwebrx/users.json. The file contains no actual passwords, and all password hashes are salted. This is in accordance with best practises for storage of credentials, and in case of a leak should make cracking an actual password hard, but can not make it impossible. The permissions of this file should therefore be as restrictive as possible.

Recommended setup: The file should be owned by the user and group that OpenWebRX runs as, and only this user should have read and write permissions to the file (chmod 0600 ...).

Special information for installations using a package repository

The Debian packages include a setup step that can create an initial user during the installation. This step will ask for a password only, the name of the user will always be "admin". You can skip this step by leaving the password blank, and create your own user(s) using the tools described above.

You can also create the "admin" user at a later time, or reset its password, by running the command dpkg-reconfigure openwebrx.

Special information for docker users

There's three basic methods to create admin users when running OpenWebRX inside a docker container:

Create an initial user through environment variables

You can set the environment variables OPENWEBRX_ADMIN_USER and OPENWEBRX_ADMIN_PASSWORD to create and persist a new user during startup of the container. This will only work if the user doesn't already exist.

The user database will be stored along the configuration files under /var/lib/openwebrx which should be located on a volume. If this has been setup correctly, the environment variables can be removed after the initial setup has succeeded.

Run admin commands through docker run

The OpenWebRX docker images will pass any arguments they receive to OpenWebRX itself. This makes it possible to run the container like this to execute admin commands:

docker run -it [... other docker arguments ...] jketterl/openwebrx-full admin adduser [username]

Please note that you probably will at least need to fill in the mount information for your configuration for this to work. More docker settings may be required depending on your setup.

Run admin commands through docker exec

This method requires an OpenWebRX docker container to be already running. You will need to identify the running container in the following command using its container id or name as [container]. This example creates a new user in the container, but you can replace the trailing command with any other command from the table above:

docker exec -it [container] python3 /opt/openwebrx/openwebrx.py admin adduser [username]