actord

    0.0.4 • Public • Published

    actord

    This service is exposing web hook for triggering custom actors.

    Running with ...

    docker

    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.

    systemd

    1. 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 actord
      usermod -L actord
    2. Extract the project's files into folder of your choice, e.g. /opt/actord.
    3. Move file actord.service to /etc/systemd/system.
    4. Open resulting /etc/systemd/system/actord.service in a text editor of your choice and
      • replace /path/to in 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 User=.
    5. Reload systemd by invoking systemctl daemon-reload.
    6. Start the service with systemctl start actord.service.
    7. Check the status and logs with journalctl -xeu actord.service.
    8. Try accessing service using browser. It's listening on port 3000, so open URL .
    9. Enable the service persistently with systemctl enable actord.service.

    Actors

    The following description assumes you have been precisely following instructions on how to run actord with systemd and thus was extracting its files into folder /opt/actord as well as having created user actord for 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:

    1. The file .token is containing a single line of text. Its content must be provided in URL of request triggering the actor.
    2. 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.

    Considerations

    Performance

    • actord features support for long running actors by detaching them from any triggering request.

    Security

    • Neither .token nor run.sh should be owned by user actord to prevent the service accidentally modifying or removing either file.
    • The actor's folder itself should be owned by user actord and 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

    Privileged Actors

    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:

    1. Make sure to comply with basic security considerations provided before.
    2. 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 root here and in next steps with name of any user you want to run the actor as instead.
    3. Configure sudo by running visudo for adding this line:
      actord = (root) NOPASSWD: /path/to/actord/actors/some-actor/.run.root.sh
      
    4. 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 sudo is 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.

    Troubleshooting

    Requesting Script Fails With Sudo Requiring TTY Or Some Askpass
    • Thoroughly check the line added with visudo again.
    • Make sure invocation of sudo in run.sh is addressing .run.root.sh using its absolute path name.
    • Even though sudo should not need to use a TTY at all it might help adding another line using visudo:
      Defaults!/path/to/actord/actors/some-actor/.run.root.sh !requiretty
      

    Using HTTPS

    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

    Keywords

    none

    Install

    npm i actord

    DownloadsWeekly Downloads

    1

    Version

    0.0.4

    License

    MIT

    Unpacked Size

    17.5 kB

    Total Files

    12

    Last publish

    Collaborators

    • simon.friedo
    • soletan