leofs-run-as-user.md

Starting from version %version, all LeoFS nodes are running as non-privileged user leofs in official Linux packages. It should work out of the box for new installations and for new nodes on existing installations. However, for existing nodes upgrading to %version (or later) from earlier versions the change might be not seamless. Compared to the usual upgrade procedure described at System Maintenance, extra steps are needed. There are a few options, depending on how the node was configured.

Users that are running installations with default paths (e.g. queue and mnesia in /usr/local/leofs/<version>/leo_*/work, log files in /usr/local/leofs/<version>/leo_*/log, storage data files in /usr/local/leofs/<version>/leo_*) and follow original upgrade procedure should do the following:

1. During upgrade of node (of any type), after stopping the old version and after copying or moving mnesia / log / queue / data files to directories with new version, change the owner with the commands below. It has to be done before launching the new version. For installation with default paths, these commands should be enough:

# chown -R leofs:leofs /usr/local/leofs/%version/leo_storage/avs
# chown -R leofs:leofs /usr/local/leofs/%version/leo_gateway/cache
# chown -R leofs:leofs /usr/local/leofs/%version/leo_*/log
# chown -R leofs:leofs /usr/local/leofs/%version/leo_*/work

2. Remove old temporary directory used by launch scripts. This step is needed because when earlier version was launched with root permissions, it creates a set of temporary directories in /tmp which cannot be re-used by non-privileged user as is, and launch scripts will fail with obscure messages - or with no message at all, except for an error in syslog (usually /var/log/messages).

# rm -rf /tmp/usr

3. Start the node through its launch script, as per upgrade flow diagram.

Users that have customized their installation and use external paths (e.g. /var/log/leofs for log files, /mnt/avs for data files and so on):

1. Before starting new version of a node, execute chown -R leofs:leofs <..> for all these external directories (log, work - mnesia and queue, avs, cache).
2. Don't forget to remove temporary directory (rm -rf /tmp/usr) as well for the reasons described above.

These users might be interested in new features of "environment" config files, which allow to redefine some environment variables like paths in launch script.

Users that have customized their launch scripts and are running leofs as non-privileged user (leofs or some other):

1. Scripts that are provided by packages generally should be enough to run on most configurations without changes. If needed, change user from leofs to some other in "environment" config files (e.g. RUNNER_USER=localuser).
2. Possible pitfall includes ownership of /usr/local/leofs/.erlang.cookie file, which is set to leofs during package installation. This should only be a problem when trying to run LeoFS nodes with permissions of some user which is not called leofs, but has home directory set to /usr/local/leofs. This is not supported due to technical reasons; home directory of that user must be set to something else.

Users that want to keep maximum compatibility with previous installation and are fine with running LeoFS nodes as root user:

1. In "environment" config file, set this option

RUNNER_USER=root

Please note that switching this node to run as non-privileged user later will require extra steps to carefully change all permissions. This is not recommended, by possible (at very least, in addition to chown commands from before, permissions of leo_*/etc and leo_*/snmp/*/db will have to be changed recursively as well).

TY, fixed