Skip to main content

7.7 Service Automation

By default, blockchain clients are not automatically starting whenever there has been a power outage or crash on your node system. This means additional manual work by logging into the node and restarting clients or services. As the LUKSO CLI manages all blockchain clients in the background, we can add a startup script to run every time on boot.

tip

Automatically restarting individual execution, consensus, or validator clients after failure requires a 🐳 Docker or 🗂️ Custom Setup. However, Grafana Notifications will inform you when specific processes stopped working.

warning

Automation is only possible from LUKSO CLI Version 0.8.1 onwards. Make sure to update to the latest version.

info

The following steps are performed on your 📟 node server.

1. Stop Node Operation​

Depending on your setup method, there are different ways to stop your node before applying updates.

cd <lukso-working-directory>
lukso stop
info

Exchange <lukso-working-directory> with the path of the node folder.

Force Client Shutdown
sudo pkill geth

2. Create System User​

As the staking node requests the validator wallet's password every time during startup, we have to write the password into a file, similar to how credentials are handled within the Dynamic DNS setup. To mitigate security risks, a separate user will be added to exclusively run the node service and read the password file.

Running services as a system user with minimal privileges is a typical best practice, as the service is not allowed to write outside of the specific client folders. It limits the potential damage if the software is somehow compromised, and hides the private credentials for the rest of the system. The node's user won't be able to write to directorieson the system or execute commands. Use the system's user creation tool to add a new one.

sudo adduser --system lukso-validator-worker --group --no-create-home
Full Command Explanation
FlagDescription
--system Creates a system user, used to run services and daemons rather than for people to log in with.
--group Creates a new group with the same name as the user.
--no-create-home Prevents the creation of a home directory, as the user is only meant to run a specific service.

If you want to confirm that the user has been created, you can search for it within the password file, housing all essential information for each user account. Using the search tool grep, we can check if the user exists within the file.

grep "lukso-validator-worker" /etc/passwd

The output should look similar to this:

lukso-validator-worker:x:120:126::/home/lukso-validator-worker:/usr/sbin/nologin

3. Add Password File​

If you run a validator node, you will need to create two new files: one for the password and one for the service automation. Start by creating a new directory for these service files directly within your node folder, where the new system user will have access to.

tip

This step can be skipped for regular nodes that do not run validators.

# Move to Home Directory
cd

# Open Node Folder
cd <lukso-working-directory>

# Create Service Folder
mkdir static

# Move into Folder
cd static

Continue to add a password file using your preferred text editor, write down your password on a single line, then save and exit.

# Create Password File
vim ./<your-filename>

# Example Name
vim ./client_dependencies
info

Exchange <your-filename> with a generic name, so even with access, users dont immediately know there is's a password.

tip

Access to this password file will be restricted within the Configure Access Rights section.

4. Add Startup Script​

After creating the password file, you can create the second service automation file, starting up the LUKSO CLI with your preferred settings and checking the network connection before doing so. Verifying that the internet connection is up before the clients are started is essential to avoid stalls or manual interventions.

If there was a power outage, the node might resume work before the router was restarted or could even connect to the internet service provider. Instead, the startup script can try to ping a public Google service first and resume work once the request was fulfilled. Otherwise, the script will wait retry. Start by creating the startup file using your preferred text editor.

vim ./lukso_startup.sh

Then continue to write down or paste the startup schedule:

#!/bin/bash
# Try to ping Google Server
while ! ping -c1 google.com &>/dev/null
do
    echo "Internet down. Google could not be pinged, retrying in 5 seconds."
    sleep 5
done
echo "Internet up. Starting the LUKSO Mainnet Node."
# If internet is up, continue with next command
exec /usr/local/bin/lukso start \
        --checkpoint-sync
Full Command Explanation
ParameterDescription
c1 Specifies to send a single package before stopping.
&>/dev/null Discard the output of the ping, as its not needed.
testnet Runs the node on the testnet instead of the mainnet.
validator Runs the node with validator keys to participate in staking.
validator-wallet-password Dymanic path to the password file based on the script's location.
transaction-fee-recipient Attaches the wallet address that will receive staking rewards.
checkpoint-sync Speeds up synchronization by lazy-loading full blockchain data.
tip

Additional flags can be attached to further customize your node, like configuring the slasher service, specifying a node name, or setting a validator graffiti. The startup script will automatically read all the client configuration files within the node folder. However, keep in mind that you will always have to add another backslash \ if you attach several flags across multiple lines.

warning

In case you are modifying the startup script, make sure to restrict permissions as regular user wont have access to it.

5. Restrict Access Rights​

To protect sensitive credentials and ensure system security, we need to restrict file access. Additional permission management prevents unauthorized access to the password file and startup script to ensure only the dedicated user can start the node.

info

Within the commands, exchange the following properties:

  • <user-name> with the name of the user you're logging into the node.
  • <lukso-working-directory> with the name of your node folder
  • <your-generic-password-file> with the name of your password file

5.1 Change Node Folder Owner: Set the new lukso-validator-worker as owner of all node directory files and configs.

sudo chown -R lukso-validator-worker:lukso-validator-worker /home/<user-name>/<lukso-working-directory>

5.2 Change LUKSO CLI Owner: Set the new lukso-validator-worker as owner of the LUKSO CLI and binaries.

sudo chown lukso-validator-worker:lukso-validator-worker /usr/local/bin/lukso

5.3 Grant Node Folder Access: Ensure the regular user still has permission to access logs and the working directory.

sudo chmod -R 750 /home/<user-name>/<lukso-working-directory>
sudo chmod 755 /home/<user-name>/<lukso-working-directory>

5.4 Restrict Password File: Ensure that only the lukso-validator-worker can read the password to start the node.

sudo chmod 400 /home/<user-name>/<lukso-working-directory>/static/<your-generic-password-file>

5.5 Restrict Startup Script: Ensure that only the lukso-validator-worker can start up the node.

sudo chmod 500 /home/<user-name>/<lukso-working-directory>/static/lukso_startup.sh

5.6 Check User Access: Ensure that the lukso-validator-worker can access the full path to the node directory.

namei -l /home/<user-name>/<lukso-working-directory>

The output should look like the following:

f: /home/<user-name>/<lukso-working-directory>
drwxr-xr-x root                    root                    /
drwxr-xr-x root                    root                    home
drwxr-x--- <user-name>             <user-name>             <user-name>
drwxr-xr-x lukso-validator-worker  lukso-validator-worker  <lukso-working-directory>
warning

By looking at the first column, you need to verify that users can read and access r-x all parent folders of the node folder. Without access --- to intermediate directories, they cant access any of the underlying folders they became the owner of.

5.7 Check User Access: Grant access to the user directory and verify lukso-validator-worker can access the node folder.

sudo chmod 755 /home/<user-name>
namei -l /home/<user-name>/<lukso-working-directory>

The output should look like the following:

f: /home/<user-name>/<lukso-working-directory>
drwxr-xr-x root                    root                    /
drwxr-xr-x root                    root                    home
drwxr-xr-x <user-name>             <user-name>             <user-name>
drwxr-xr-x lukso-validator-worker  lukso-validator-worker  <lukso-working-directory>

6. Configure Service File​

After the user, files, and permissions are in place, you can configure the actual system service that is going to execute our startup script once the system boots. Create a new service file in the system's directory using your preferred text editor.

sudo vim /etc/systemd/system/lukso-validator.service

Then continue to write down or paste the service properties and descriptions for your preferred logging tool.

[Unit]
Description=LUKSO Validator Service
Documentation=https://github.com/lukso-network/tools-lukso-cli
Wants=network-online.target
After=network-online.target

[Service]
User=lukso-validator-worker
Group=lukso-validator-worker
Type=oneshot
RemainAfterExit=yes
WorkingDirectory=/home/<user-name>/<lukso-working-directory>
ExecStart=/home/<user-name>/<lukso-working-directory>/static/lukso_startup.sh
ExecStop=/usr/local/bin/lukso stop
SyslogIdentifier=lukso-validator
StandardOutput=journal
StandardError=journal

[Install]
WantedBy=multi-user.target
Full Property Explanation
PropertyDescription
DescriptionA human-readable label for the service, shown in systemctl status.
DocumentationURL to relevant documentation for setup or troubleshooting.
WantsThe service should try to start network-online.target before starting the validator service.
AfterEnsures the service starts only after the network is online via network-online.target.
UserExecutes the service as the lukso-validator-worker user.
GroupExecutes the service under the lukso-validator-worker group.
TypeSet to oneshot, meaning the command runs once and considers the service to be started.
RemainAfterExitKeeps the service in an active state, even when exited, to save logs for long-running processes.
WorkingDirectoryDefines that the service command will be executed in the <lukso-working-directory>.
ExecStartThe lukso_startup.sh script that will be started from the service.
ExecStopCommand to stop the validator service using lukso stop once clients are up and running.
SyslogIdentifierTags logs from the service with lukso-validator to help distinguish them from other logs.
StandardOutputSends regular service logs to the journal or syslog system.
StandardErrorSends error service logs to the journal or syslog system.
WantedByBinds the service to the multi-user.target, so it starts during all boot processes.
info

Exchange the following properties:

  • <user-name> with the name of the user you're logging into the node.
  • <lukso-working-directory> with the name of your node folder
warning

Ensure there are no missing or unintended spaces, characters or linebreaks before saving the service configuration.

danger

In case you set different User and Group names, ensure that they are spelled correctly within the service file. If the exact user name cant be found, system services will fall back to use the root permissions, creating security risks.

After you saved and exited the service file, you will need to update the system manager configuration, ensuring that all file changes are included within the current system setup. Use the system control command to reload them.

sudo systemctl daemon-reload

7. Restart the Node​

After setting up the service and configuring file access, you can enable and start the systemd service.

7.1 Enable Start Boot: Enable autostarts of the node process during system boot.

sudo systemctl enable lukso-validator

The output should look similar to this:

Created symlink /etc/systemd/system/multi-user.target.wants/validator-validator.service → /etc/systemd/system/lukso-validator.service.

7.2 Startup Service: Once enabled, you can start the automated node startup using the system control command:

sudo systemctl start lukso-validator

8. Check Service Status​

You can fetch the current status from the system control to check if the node service is running and configured correctly. The command will display whether it is active, enabled, or disabled and show recent log entries.

sudo systemctl status lukso-validator

The output should look similar to this:

● validator.service - LUKSO Validator Node
     Loaded: loaded (/etc/systemd/system/validator.service; enabled; vendor preset: enabled)
     Active: active (exited) since [DATE] UTC; [TIME] ago
       Docs: https://github.com/lukso-network/tools-lukso-cli
   Main PID: 9096 (code=exited, status=0/SUCCESS)
      Tasks: 26 (limit: 4694)
     Memory: 1.1G
     CGroup: /system.slice/validator.service
             [PID] geth --config=./configs/testnet/geth/geth.toml
             ├─[PID] prysm --log-file=./testnet-logs/prysm_2025-06-06_14-43-01.log --accept-terms-of-use --config-file=./configs/testn>
             └─[PID] validator --accept-terms-of-use --config-file=./configs/testnet/prysm/validator.yaml --log-file=./testnet-logs/va>

[DATE] [TIME] [USER] validator[9096]: time="2025-06-06T14:43:13Z" level=info msg="✅  Validator started! Use 'luk>
[DATE] [TIME] [USER] validator[9096]: time="2025-06-06T14:43:13Z" level=info msg="🎉  Clients have been started. >
...
[DATE] [TIME] [USER] systemd[1]: Finished LUKSO Validator Node.
tip

You can still check the status of the node using the LUKSO CLI, however, you always have to use the superuser permission. As you have a separate user to run the service, only root or lukso-validator-worker are permitted to fetch the service information like lukso status or lukso logs. By default, the CLI will always show the processes as stopped, even if they are running.

# Move to Home Directory
cd

# Enter Node Folder
cd <lukso-working-directory>

# Check Processes
sudo lukso status
info

Exchange <lukso-working-directory> with the path of the node folder.

Depending on the clients you use, output should look similar to this:

INFO[0000] PID 9409 - Execution ([EXECUTION_CLIENT_NAME]): Running 🟢
INFO[0000] PID 9419 - Consensus ([CONSENSUS_CLIENT_NAME]): Running 🟢
INFO[0000] PID 9426 - Validator ([VALIDATOR_CLIENT_NAME]): Running 🟢

Maintenance​

Proper maintenance ensures that all the components are working as intended and can be updated on the fly.

warning

The service starts the LUKSO CLI as if its directly run within your node folder, just by a specific user with limited permissions and the exclusive right to view the validator password. All CLI commands can be executed as before using root permissions, however, never execute sudo lukso start, as it will restart the clients with full root privilages, entailing security risks.

Logging: Check the latest status of the system service.

sudo journalctl -f -u lukso-validator
tip

Further details about checking client logs files can be found on the Problem Scanning page.

Starting: If you made any changes or updates to configuration, reload the system daemon and start the node.

sudo systemctl daemon-reload
sudo systemctl restart lukso-validator

Stopping: You can stop all the node clients and parent processes using the system control.

sudo systemctl stop lukso-validator
tip

Further information about system control or logging can be found on the Utility Tools page in the 🧠 Theory section.

Revert Setup​

If something went wrong, you can remove the user or delete the service and related files all together.

info

Within the commands, exchange the following properties:

  • <user-name> with the name of the user you're logging into the node.
  • <lukso-working-directory> with the name of your node folder

1. Stop the Node Service: First, stop the blockchain clients using the configured service.

sudo systemctl stop lukso-validator

2. Change Folder Ownership: Change the owner of the node folder back to your regular node user.

sudo chown -R <user-name>:<user-name> /home/<user-name>/<your-working-directory>

3. Change LUKSO CLI Ownership: Revert the ownership of the LUKSO CLI back to as it was before.

sudo chown root:root /usr/local/bin/lukso

4. Restrict User Directory: Set exclusively access to your user's home directory again.

sudo chmod 750 /home/<user-name>

5. Remove System User: Remove the lukso-validator-worker user, group, and files, so there is no orphaned data.

sudo deluser --remove-all-files lukso-validator-worker
sudo delgroup lukso-validator-worker

6. Disable Node Service: Remove the service link from the system's boot.

sudo systemctl disable lukso-validator

7. Remove Service File: Delete the service configuration file from the system folder.

sudo rm /etc/systemd/system/lukso-validator.service

8. Reload System Service: Reload the system daemon to apply latest service updates.

sudo systemctl daemon-reload

9. Remove Startup Files: Delete the password file and startup script within the node folder.

rm -rf <lukso-working-directory>/static