Skip to main content

Troubleshooting

This section provides guidance on common troubleshooting practices, including setting up logging and verifying authentication key ownership. Following these steps will help ensure smoother diagnostics and support.

Log Inspection​

To effectively monitor and troubleshoot the USP components, you can either rely on systemd logs using journalctl or configure dedicated log files.

Option 1: Using journalctl (Systemd-based Logging) ​

If you have not configured a log file path, then systemd will collect all the logs. You can inspect them using:

sudo journalctl -u <Service Name> -f

Replace <Service Name> with the appropriate systemd service name, such as usp-manager, usp-server or usp-client.

Option 2: Setting Up Dedicated Log Files​

If you have configured a log file path, then the logs will be written in the corresponding log file. You can access them using the following command:

cat /path/to/your/log/file
tip

If you have configured a log file path, but there is a problem with another configuration parameter impeding a component to start successfully, logs will be collected by systemd and option 1 will let you see the configuration error logs.

File Ownership and Permissions​

USP processes run under the udmg user, so all files required at runtime must be accessible by that user. Correct ownership and permissions are critical for both functionality and security.

There are two main categories of files to consider:

Authentication Keys and Certificates​

These include private keys used for SSH tunnels, mTLS connections, or inbound node authentication. They must be tightly secured; otherwise, USP components may fail to start or expose sensitive data.

  • Owner: udmg (the user running the USP service)
  • Group: udmg (the service group)
  • Permissions: 600 (read and write for owner only)

Example command to set permissions correctly, replacing /path/to/key.pem with the actual file location:

chown udmg:udmg /path/to/key.pem
chmod 600 /path/to/key.pem
warning

Authentication keys must not be readable by other users. Improper permissions or ownership can cause startup failures or security risks.

Configuration Files​

These include the USP component configuration files distributed via the RPM/DEB packages (.hcl and .env files). They typically do not contain sensitive information, but they must still be readable by the udmg user.

  • Owner: root or udmg
  • Group: root or udmg
  • Permissions:
    • 644 (recommended for files owned by root)
    • 640 (if group-owned by udmg)

Default package behavior:

  • .hcl and .env files are installed as root:root with 644 permissions.
  • This works because the udmg user has read access via the “others” permission.