This service is exposing web hook for triggering custom actors.
Running with ...
docker build -t actord .docker run -P actord
This docker container is limited to work with files in that container, only. You might want to bind folder containing your desired actors to /app/actors. In addition you might e.g. need to bind the socket controlling docker so actors are capable of performing actions beyond scope of this container,
docker run -P -v /path/to/your/actors:/app/actors,ro actord
Keep in mind that scripts of any actor bound this way are still limited to accessing the filesystem of the container by default.
- Create a new user that's not used with any other application on your server. Let's name it
actord:useradd -d /dev/null -s /bin/false actordusermod -L actord
- Extract the project's files into folder of your choice, e.g. /opt/actord.
- Move file actord.service to /etc/systemd/system.
- Open resulting /etc/systemd/system/actord.service in a text editor of your choice and
/path/toin line starting with
WorkingDirectory=with the path name of folder this tool has been extracted to before.
- ensure user created before is named in line starting with
- Reload systemd by invoking
- Start the service with
systemctl start actord.service.
- Check the status and logs with
journalctl -xeu actord.service.
- Try accessing service using browser. It's listening on port 3000, so open URL .
- Enable the service persistently with
systemctl enable actord.service.
The following description assumes you have been precisely following instructions on how to run
systemdand thus was extracting its files into folder /opt/actord as well as having created user
actordfor running it. Please adopt the following instructions on having chosen different values.
Every actor is defined by adding a subfolder in /opt/actord/actors. For example, the subfolder /opt/actord/actors/some-actor defines an actor named some-actor implicitly.
Such a folder consists of at least two files:
- The file .token is containing a single line of text. Its content must be provided in URL of request triggering the actor.
- The script file run.sh gets invoked on a valid request via exposed web service. Its exit code and output on stdout as well as stderr is passed back to the requesting client in a JSON record.
actordfeatures support for long running actors by detaching them from any triggering request.
- Neither .token nor run.sh should be owned by user
actordto prevent the service accidentally modifying or removing either file.
- The actor's folder itself should be owned by user
actordand hidden from world access to make it available to the user
actord, only. This prevents other users from reading your .token file or any other sensitive detail about your desired actions.
Listing the resulting folder with
ls -la should look like this:
drwxr-x--- 2 actord root 4096 Sep 28 21:43 .drwxr-xr-x 3 root root 4096 Sep 28 20:42 ..-rwxr-xr-x 1 root root 86 Sep 28 21:43 run.sh-rw-r--r-- 1 root root 40 Sep 28 20:43 .token
When running the service with systemd as described before any actor's run.sh script file is run as the non-privileged user
actord. This improves security e.g. for running the service without privileged access, but limits an actor's possibilities in run.sh. However, by using
sudo it is possible to safely elevate actor's permissions:
- Make sure to comply with basic security considerations provided before.
- Put another script, e.g. named .run.root.sh, into the actor's folder. This file should be visible to user
root, only. Optionally, replace
roothere and in next steps with name of any user you want to run the actor as instead.
visudofor adding this line:
actord = (root) NOPASSWD: /path/to/actord/actors/some-actor/.run.root.sh
- Put this into run.sh:sudo -u root /path/to/actord/actors/some-actor/.run.root.sh
Make sure to use the file's absolute path name here so
sudois matching lines, properly.
Now, listing the resulting folder with
ls -la should look like this:
drwxr-x--- 2 actord root 4096 Sep 28 21:43 .drwxr-xr-x 3 root root 4096 Sep 28 20:42 ..-rwxr-x--- 1 root root 54 Sep 28 21:00 .run.root.sh-rwxr-xr-x 1 root root 86 Sep 28 21:43 run.sh-rw-r--r-- 1 root root 40 Sep 28 20:43 .token
All your actor's elevated operations should be placed in .run.root.sh eventually. Consider limiting privileged access to parts of actor essentially requiring it. When running with privileged permissions you should not process any stuff fetched from external sources without another validation.
Requesting Script Fails With Sudo Requiring TTY Or Some Askpass
- Thoroughly check the line added with
- Make sure invocation of
sudoin run.sh is addressing .run.root.sh using its absolute path name.
- Even though
sudoshould not need to use a TTY at all it might help adding another line using
actord is built with hitchy. The latter features support for HTTPS just by using additional command line arguments passed on invoking
npm start to provide names of files containing key and certificate required for SSL encryption:
npm start -- --sslKey=/path/to/key.pem --sslCert=/path/to/cert.pem --sslCaCert=/path/to/chain.pem