Install LucidLink and manage a client systemd service to survive system reboot, re-activate and automatically mount Filespace in the preferred system location.
An automated script which takes various arguments and generates a systemd service along with the various script options available for managing your Filespace and systemd configuration.
Advanced systemd unit file configuration techniques are available within this KB article on manual implementations.
Requires a user appropriately privileged to perform systemd systemctl operations. Root or a member of sudo group or the sudoers file modified accordingly for your user or group.
Install LucidLink client. It is recommended your distribution is up-to-date.
Debian based (.deb):
wget https://www.lucidlink.com/download/latest/lin64/stable/ -O lucidinstaller.deb sudo apt install ./lucidinstaller.deb -y
Red Hat based (.rpm):
wget https://www.lucidlink.com/download/latest/lin64-rpm/stable/ -O lucidinstaller.rpm sudo yum install lucidinstaller.rpm
Download and allow executing of our lucid_systemd.sh script.
wget https://lucidlink-support.s3.amazonaws.com/scripts/lucid_systemd.sh -O lucid_systemd.sh chmod +x lucid_systemd.sh
sudo ./lucid_systemd.sh
Usage: ./lucid_systemd.sh [options]
Request failed with: Bad Request
Lucid options:
--instance <id> Daemon instance.
--fs <filespace.domain> Filespace and domain name (required).
--user <fsusr> Filespace username.
--password <fsusrpwd> Filespace user password.
--mount-point <mount> Filespace mount-point.
--all-snapshots Activate in snapshots mode
--snapshot <id> Activate the snapshot instead of the live Filespace
--root-path <rootpath> Root-path (metadata / cache) location.
--config-path <configpath> Config-path {Lucid.log .json) location.
--fuse-allow-other Allow other users on this machine to access the filesystem
systemd options:
--sysd-user <sysdusr> systemd unit user.
--sysd-group <sysdgroup> systemd unit group.
--sysd-workdir <sysdwkdir> systemd unit working directory.
--sysd-file <unitfile> systemd service file.
Advanced options:
--list <unitfile> List systemd service.
--list-all List systemd services with description beginning 'LucidLink'.
--start <unitfile> systemctl start specified service.
--status <unitfile> systemctl status of specified service.
--stop <unitfile> systemctl stop specified service.
--enable <unitfile> systemctl enable specified service.
--disable <unitfile> systemctl disable specifed service.
--daemon-reload systemctl daemon-reload.
--remove <unitfile> Remove disabled systemd service.
--replace <unitfile> Override existing systemd service.
Example: ./lucid_systemd.sh --fs filespace.domain --user root --password Abcd1234 --mount-point /media/lucid --sysd-user user --sysd-group group --sysd-workdir /home/user --sysd-file filespace-domain.service
Our script allows you to perform all operations to link to the live Filespace, a particular snapshot or all snapshots, along with multiple daemon instances and specify the instance root-path for the metadata and file data cache.
systemd user, group and working directories can be specified to run as a certain user, and allow Filesystem in Userspace (FUSE) allow other to provision access to other users on the system for access the mount-point.
systemd management options of listing units, enabling, disabling, starting, stopping and removing as well as replacing an existing unit file with an alternate configuration if you'd like to modify or substitute arguments.
Install basic systemd unit assumes default configuration and runs as root, linking and mounting utilizing the Filespace root user.
sudo ./lucid_systemd.sh --fs <filespace.domain> --password <rootpwd>
Example. Replace arguments and <brackets>.
sudo ./lucid_systemd.sh --fs filespace.domain --password Abcd1234
Passwords with special characters will require wrapping in order to avoid certain characters which are significant to the Bash shell and likely to being misinterpreted.
Our script should accommodate many of the most complex password requirements. It is best-practice to maintain complex passwords for your Filespace credentials.
Wrap your --password with either quoting combination of "'Abcd|;&1234'" or '"Abcd|;&1234"' however in some cases you might require escaping. See this KB article.
Complex password escaping assuming our password is wrapped in double " quotes already as "complex~^@|;&$*pwd".
sudo ./lucid_systemd.sh --fs filespace.domain --password '\"complex~^@|;&$*pwd\"'
or
systemd-escape '"complex~^@|;&$*pwd"'
sudo ./lucid_systemd.sh --fs filespace.domain --password '\x22complex\x7e\x5e\x40\x7c\x3b\x26\x24\x2apwd\x22'
Consult our advanced systemd KB which utilizes systemd-escape and conceals the password through an environment variable.
Example successful script output.
systemd unit file 'filespace-domain.service'
# ------------------------------------------------------------------
# AUTHOR: [LucidLink Support]
# NAME: filespace-domain.service
# DESCRIPTION: luicd_systemd.sh filespace.domain daemon
# generated systemd unit file.
#
# THE SCRIPT IS PROVIDED “AS IS” AND “AS AVAILABLE” AND IS WITHOUT
# WARRANTY OF ANY KIND. PLEASE REVIEW ALL TERMS AND CONDITIONS.
# https://www.lucidlink.com/legal-documents
# ------------------------------------------------------------------
[Unit]
Description=LucidLink filespace.domain Daemon
After=network-online.target
[Service]
#User=<user>
#Group=<group>
#WorkingDirectory=/home/<user>
ExecStart=/usr/bin/lucid daemon --fs filespace.domain --password Abcd1234
ExecStop=/usr/bin/lucid --exit
Restart=on-abort
[Install]
WantedBy=multi-user.target
Moving 'mv filespace-domain.service /etc/systemd/system'
Enabling 'systemctl enable filespace-domain.service'
Created symlink /etc/systemd/system/multi-user.target.wants/filespace-domain.service → /etc/systemd/system/filespace-domain.service.
Starting 'systemctl start filespace-domain.service'
Lucid is currently not running.
Client state: Linking (Setting up the link procedure...)
Client state: Linking (Starting the metadata services...)
Client state: Linking (Mounting the Filespace...)
Client state: Linked
Filespace object store state: connected
Filespace object store download latency: low
Filespace object store upload latency: low
Filespace service state: connected
Filespace file index: up-to-date
Filespace name: filespace.domain
Filespace id: 9e89cc21-cdb2-43d4-9165-7cfbc70ceee5
Filespace block size: 256KiB
Filespace encryption mode: full encryption
Filespace bucket name: filespace-domain-9e89cc21-cdb2-43d4-9165-7cfbc70ceee5
Filespace compression: lz4
Filespace maximum file size: 512TiB
Filespace object store bucket name: filespace-domain-9e89cc21-cdb2-43d4-9165-7cfbc70ceee5
Filespace object store protocol: https
Filespace object store provider: AWS
Filespace object store type: s3
Filespace object store region: ap-southeast-2
Filespace object store endpoint: s3.ap-southeast-2.amazonaws.com
Filespace object store virtual addressing: off
Filespace object store location constraint: off
Filespace mode: live
Filespace internal version: 4
Filespace format: 2.0
Root directory: /root/.lucid/
Mount point: /media/filespace
Root point:
Daemon mode: application
User: lucid\root [Administrator]
Known service version: 2.4.4685
Status 'systemctl status filespace-domain.service'
● filespace-domain.service - LucidLink filespae.domain Daemon
Loaded: loaded (/etc/systemd/system/filespace-domain.service; enabled; preset: enabled)
Active: active (running) since Sat 2023-06-24 21:59:40 UTC; 4s ago
Main PID: 251739 (Lucid)
Tasks: 148 (limit: 2323)
Memory: 10.9M
CPU: 189ms
CGroup: /system.slice/filespace-domain.service
├─251739 /bin/bash /opt/lucidapp/resources/Lucid daemon --fs filespace.domain --password Abcd1234
└─251746 ./Lucid.bin daemon --fs filespace.domain --password Abcd1234
You will note that filespace-domain.service unit file installed in /etc/systemd/system enabled and started. Can be modified as a typical systemd unit file, and controlled by conventional systemctl operations.
Although let us assume you made a mistake and got the password wrong for example.
sudo ./lucid_systemd.sh --fs filespace.domain --password Wrong
Example failed script output.
systemd unit file 'filespace-domain.service'
# ------------------------------------------------------------------
# AUTHOR: [LucidLink Support]
# NAME: tfilespace-domain.service
# DESCRIPTION: luicd_systemd.sh filespace.domain daemon
# generated systemd unit file.
#
# THE SCRIPT IS PROVIDED “AS IS” AND “AS AVAILABLE” AND IS WITHOUT
# WARRANTY OF ANY KIND. PLEASE REVIEW ALL TERMS AND CONDITIONS.
# https://www.lucidlink.com/legal-documents
# ------------------------------------------------------------------
[Unit]
Description=LucidLink filespace.domain Daemon
After=network-online.target
[Service]
#User=<user>
#Group=<group>
#WorkingDirectory=/home/<user>
ExecStart=/usr/bin/lucid daemon --fs filespace.domain --password Wrong
ExecStop=/usr/bin/lucid exit
Restart=on-abort
[Install]
WantedBy=multi-user.target
Moving 'mv filespace-domain.service /etc/systemd/system'
Enabling 'systemctl enable filespace-domain.service'
Created symlink /etc/systemd/system/multi-user.target.wants/filespace-domain.service → /etc/systemd/system/filespace-domain.service.
Starting 'systemctl start filespace-domain.service'
Lucid is currently not running.
Client state: Linking (Discovering the service info...)
Client state: Unlinking (Stopping the client...)
Lucid is currently not running.
Status 'systemctl status filespace-domain.service'
× filespace-domain.service - LucidLink filespace.domain Daemon
Loaded: loaded (/etc/systemd/system/filespace-domain.service; enabled; preset: enabled)
Active: failed (Result: exit-code) since Sat 2023-06-24 22:32:12 UTC; 1s ago
Duration: 1.493s
Process: 252272 ExecStart=/usr/bin/lucid daemon --fs filespace.domain --password Wrong (code=exited, status=73)
Main PID: 252272 (code=exited, status=73)
CPU: 46ms
We can utilize the scripts --replace option to replace existing filespace-domain.service with correct password.
sudo ./lucid_systemd.sh --fs filespace.domain --password Abcd1234 --replace filespace-domain.service
Now that we've got the hang of the basics, lets explore some more advanced common use cases.
Administrators would typically utilize a specific Filespace user credentials and or run as a certain Linux user, equally there is often a requirement to relocate the client cache.
Let us take a look at what our command-line arguments would look like. We will parse these commands individually however note you can combine all options, in virtually any combination.
As we've demonstrated with our previous --replace option example to repair our incorrect password, we can evolve all below examples with the same unit file. Or alternatively generate multiple individual systemd services for additional daemons with their own instance ID.
Specify a Lucid user, runs as root.
sudo ./lucid_systemd.sh --fs <filespace.domain> --user <fsuser> --password <fsusrpwd>
Configure a specific Linux user, group and working directory to run the daemon.
sudo ./lucid_systemd.sh --fs <filespace.domain> --user <fsuser> --password <fsusrpwd> --sysd-user <user> --sysd-group <group> --sysd-workdir /home/<user>
Specifies a particular root-path for metadata and file data cache, along with FUSE allow_other. Which modifies /etc/fuse.conf automatically.
sudo ./lucid_systemd.sh --fs <filespace.domain> --user <fsuser> --password <fsusrpwd> --sysd-user <user> --sysd-group <group> --sysd-workdir /home/<user> --root-path /media/<mount> --fuse-allow-other
Another configuration our administrators would like to achieve is mounting an additional daemon instance. Our script will enable you to create multiple systemd unit files for individual daemon instances.
You could be mounting for various reasons, like your snapshots or an individual snapshot. Or you could be performing a data migration between the live Filespace, and an archive Filespace or moving data between object storage providers.
Our daemon --instance option allows you to specify multiple daemon instances for this very purpose.
Launches a daemon instance 1.
sudo ./lucid_systemd.sh --instance 1 --fs <filespace.domain> --user <fsuser> --password <fsusrpwd>
If you are specifying a differenent Filespace, your systemd unit file will be automatically generated.
Instances work exactly the same as the default daemon. When manging instances you simply uselucid --instance <id> <command>.
All other command-line argument can be added if necessary.
sudo ./lucid_systemd.sh --instance <id> --fs <filespace.domain> --user <fsuser> --password <fsusrpwd> --sysd-user <user> --sysd-group <group> --sysd-workdir /home/<user> --sysd-file <unitfile> --root-path /media/<mount> --fuse-allow-other
Runs an instance and mounts all snapshots as instance 1000.
sudo ./lucid_systemd.sh --instance 1000 --fs <filespace.domain> --user <fsuser> --password <fsusrpwd> --all-snapshots --sysd-file <unitfile> --mount-point /media/snapshots
If you already have the live Filespace mounted, you will need to specify a separate instance ID, systemd unit file ending in.serviceand an alternate--mount-point.
Mounts a particular snapshot ID as instance 1000.
sudo ./lucid_systemd.sh --instance 1000 --fs <filespace.domain> --user <fsuser> --password <fsusrpwd> --snapshot <ID> --mount-point /media/snapshot --sysd-file <unitfile>
We covered the typical use cases which our Linux administrators wish to accomplish. Now it is time to look at some of the management and monitoring functions of our script.
You would traditionally manage systemd via systemctl. In our script however we've strived to simplify certain commonly utilized operations.
To list your Filespace systemd unit files generated by this script you can use --list-all to display the unit files containing a description including "LucidLink".
sudo ./lucid_systemd.sh --list-all
UNIT FILE STATE PRESET
filespace-domain.service enabled enabled
1 unit files listed.
To list an individual systemd unit file, specify it with --list.
sudo ./lucid_systemd.sh --list filespace-domain.service
Disabling, enabling is as simple as --disable or --enable. This ensures that the service starts or otherwise on system boot.
sudo ./lucid_systemd.sh --disable filespace-domain.service
UNIT FILE STATE PRESET
filespace-domain.service disabled enabled
1 unit files listed.
sudo ./lucid_systemd.sh --enable filespace-domain.service
UNIT FILE STATE PRESET
filespace-domain.service enabled enabled
1 unit files listed.
Stopping or starting a service is --stop and --start, along with --status to view if the service is active or inactive.
./lucid_systemd.sh --stop filespace-domain.service
./lucid_systemd.sh --status filespace-domain.service
○ filespace-domain.service - LucidLink testv4.filesystem Daemon
Loaded: loaded (/etc/systemd/system/filespace-domain.service; enabled; preset: enabled)
Active: inactive (dead)
./lucid_systemd.sh --start filespace-domain.service
● filespace-domain.service - LucidLink filespace.domain Daemon
Loaded: loaded (/etc/systemd/system/filespace-domain.service; enabled; preset: enabled)
Active: active (running) since Sun 2023-06-25 23:06:56 UTC; 8s ago
Main PID: 261546 (Lucid)
Tasks: 148 (limit: 2323)
Memory: 11.9M
CPU: 158ms
CGroup: /system.slice/filespace-domain.service
├─261546 /bin/bash /opt/lucidapp/resources/Lucid daemon --fs filespace.domain --password Abcd1234
└─261549 ./Lucid.bin daemon --fs filespace.domain --password Abcd1234
Jun 25 23:06:57 ubuntu-s-1vcpu-2gb-intel-syd1-01 lucid[261549]: 2023-06-25T23:06:57.782618Z | I | 261549 | FileSystemClient | filespace started.
Remove stops, disables, removes the systemd unit file and reloads the systemd daemon.
sudo ./lucid_systemd.sh --remove filespace-domain.service
As showcased earlier in our article, --replace is an extremely versatile command. When specified it will substitute a daemon unit file with the new arguments provided in the command syntax. There is no need to remove, simply update an existing.
sudo ./lucid_systemd.sh <arguments> --replace <unitfile>
Replace can be used to correct mistakes, or configurational changes that are required on the system. It will stop, disable, remove and reload the systemd daemon and then apply the newly specified command-line arguments.
If you have any queries or challenges, please do not hesitate to reach out to our support via a ticket. We will be happy to provide assistance.
Please provide any error messages you encounter, your unit file output, obfuscating any sensitive information.
Consider launching the daemon command in isolation on the same system to reproduce the issue.
- lucid_systemd.sh10 KB