Managing the Server with Commands

Besides starting the server, the SpaceBuilder executable (setfn-spacebuilder) includes management commands that you run in a terminal. Use them to recover accounts and access restrictions when you cannot sign in to the admin page, or to check settings such as the port and language.

This document is a reference for administrators who install and operate the server. Manage the server in the admin page in normal operation, and use commands only when the admin page is not available.

Before you begin

• Run the commands in a terminal on the computer where SpaceBuilder is installed.
• Run them as the same operating system user that runs SpaceBuilder. The default configuration path is under that user's home folder. If you use a custom path, select the same configuration file as the running server.
• The examples assume that the executable is in the home folder (~/setfn-spacebuilder). If you placed it elsewhere, enter that path instead.
• Stop the server before running management commands that start with user, unblock, ip, admin, login, or logout.

Select the running server's configuration path

On Linux, the default configuration file is ~/.config/SetFN/config.yaml. If the service runs under another user or uses a custom configuration path, check the path in the service's startup command.

Use -c or --config to select that file. The following examples are for a server using /srv/setfn/config.yaml. Replace it with your actual file path.

~/setfn-spacebuilder -c /srv/setfn/config.yaml port get
~/setfn-spacebuilder -c /srv/setfn/config.yaml user list

Include the same -c option with the other management commands in this document. If the server uses -H or --home, match that option too. When both are given, -c takes precedence when selecting the configuration file.

Stop and start the server

Commands for users, access restrictions, and device registration, as well as admin status and admin logout-all, open the server database directly. If another process is using the same database, the command may end with Database is still locked after retrying. admin reset-config deletes the configuration file without opening the database, but stop the server before running it too.

If you set up auto-start, stop the server first.

sudo systemctl stop setfn-spacebuilder

Run the commands you need, and then start the server again.

sudo systemctl start setfn-spacebuilder

If the server is running directly in a terminal, press Ctrl+C in that terminal to stop it.

Set the console access password

The user and unblock commands ask for a Console Access Password when they run. This password is the value of the SETFN_CONSOLE_PASSWORD environment variable. Set the value in the same terminal before you run the command.

export SETFN_CONSOLE_PASSWORD="a password you choose"

This value verifies access to local console commands. Setting it does not change a Workspace administrator password or a SetFN account password. At Console Access Password, enter the value you set in this terminal.

Commands at a Glance

To see the detailed options of a command, add --help after it.

~/setfn-spacebuilder user --help

Recover Access When You Cannot Sign In

Stop the server and set the console access password before you run the commands below.

Lift a login block

If the administrator is blocked after repeated sign-in failures, add the IP of the computer you connect from to the security whitelist.

~/setfn-spacebuilder unblock --ip 203.0.113.10

Check the current recovery status with the following command.

~/setfn-spacebuilder unblock --status

If you still cannot connect after adding the IP, turn off login security temporarily.

~/setfn-spacebuilder unblock --all

~/setfn-spacebuilder unblock --enable-security

Identify the target user account

To change a password or role, you need the login username of an existing Workspace account. Check the user list with the following command.

~/setfn-spacebuilder user list

Replace the entire <username> placeholder in the examples below with the login username shown in the Username column. The Nick column contains the display name.

Change the administrator password

~/setfn-spacebuilder user password -u "<username>" --password "new password"

Replace <username> with the login username of the account whose password you want to change. Because the command you type remains in the terminal history, we recommend changing the password once more in the admin page after you sign in. The new password must follow the server's password rules, and commonly used or breached passwords are rejected. On newly installed servers, the default rule is at least 12 characters.

Turn off administrator two-factor authentication

Use this when an administrator has lost both the authenticator app and the recovery codes and cannot sign in, and there is no other superuser who can reset it from the administrator page.

~/setfn-spacebuilder user mfa reset "<username>"

The account's authenticator app registration and recovery codes are removed, and all of its signed-in sessions are ended. The next sign-in uses the password only; if the Require two-factor authentication for administrators policy is on, the user must set it up again after signing in. The action is recorded in the audit log as Two-factor reset. Running it on an account that does not use two-factor authentication changes nothing and only shows a notice. For the setup procedure, see Set up administrator two-factor authentication.

Regain administrator permission

If no account has administrator permission, change the role of an existing user.

~/setfn-spacebuilder user promote -u "<username>" -r admin

Use the existing account's login username for -u. In -r admin, admin is the administrator role to assign. In admin status, admin is the administrative command group.

Add and delete user accounts

~/setfn-spacebuilder user add -u newadmin -n "New Admin" --admin

To delete an account, specify the username. The last administrator cannot be deleted.

~/setfn-spacebuilder user delete -u olduser

Manage the IP Access Restriction

When the IP access restriction is on, only the IPs in the allowed list can access the admin page. Use the commands to fix the list when a wrong setting keeps you from reaching the admin page.

Check the current status and the allowed list.

~/setfn-spacebuilder ip status

Add or remove an IP address or a CIDR range.

~/setfn-spacebuilder ip add --ip 192.168.1.100
~/setfn-spacebuilder ip add --ip 192.168.1.0/24
~/setfn-spacebuilder ip remove --ip 192.168.1.100

Turn the restriction on or off.

~/setfn-spacebuilder ip enable
~/setfn-spacebuilder ip disable

Check Server Settings

~/setfn-spacebuilder port get
~/setfn-spacebuilder homepath get
~/setfn-spacebuilder lang get

• You can change the language of terminal messages right away, for example with lang set en.
• port set <port> and homepath set <path> do not change the value. They show what to enter in the configuration file, and port set also shows whether the port is available. The change takes effect after you edit the configuration file and restart the server.
• Valid ports are 3000 through 65535. The default port is 8510.

Recover the device connection to a SetFN account

These commands manage the connection between the server device and a SetFN account. Use the earlier user and unblock commands for Workspace user passwords and login blocks.

Stop the server and use the same configuration path as the server when starting the connection.

~/setfn-spacebuilder login

Follow the authentication instructions in the terminal and approve the connection in your browser. To repeat registration for an already registered device, use the following command.

~/setfn-spacebuilder login --force

If expired or invalid authentication information requires a new connection, remove the existing connection and register again.

~/setfn-spacebuilder logout
~/setfn-spacebuilder login --force

By default, logout clears the local site tokens, device key, and identity file. logout --unlink is a compatibility option with the same full-unlink behavior. Use logout --keep-link to clear only site session tokens while keeping the device key and identity file.

After reconnecting, restart the server and check the license registration status in the admin page.

Manage Server Status and Sign-in Sessions

Check the server status and current settings.

~/setfn-spacebuilder admin status

If you suspect that account information has been leaked, sign out all users. Users must sign in again.

~/setfn-spacebuilder admin logout-all

For backing up and restoring the knowledge storage, see Operating Knowledge Storage.

Good to Know

• Linux keeps only the first 15 characters of a process name, so ps -e and top show setfn-spacebuil. To check whether the server is running, use pgrep -f setfn-spacebuilder.
• For tasks that you can do in the admin page, such as adding users and managing blocks, we recommend using the admin page. The account and block commands can run only while the server is stopped.

Related Documents

• Installing on Linux
• Block Management
• Set up administrator two-factor authentication
• Operating Knowledge Storage
• Troubleshooting Guide