PARIDE
Sign in
Italiano

PARIDE › User guides › Installing an agent

Installing an agent

The agents (paride-agent) are the machines that build for the server: Linux, Windows or macOS, even more than one, even the same machine as the server. Today an agent connects, gets approved and stays connected; builds arrive with phase F3. Installing it now prepares the machines.

These are the steps for Debian 13. With version 1.0 the paride-agent package will do them.

What you need

  • the .NET 10 runtime, as for the server (Installing the server, step 1); on the server's machine it is already there;
  • the folder of the paride-agent program, from Download;
  • the name and port of the server, given by the administrator.

The agent runs with its own user, parideagent, different from the server's even on the same machine: it will build code that comes from the server, and a build must not be able to read the server's data.

1. User and program

sudo useradd --system --user-group --home-dir /var/lib/paride-agent --no-create-home \
             --shell /usr/sbin/nologin parideagent
sudo install -d -m 0755 /usr/lib/paride-agent
sudo cp -r paride-agent/. /usr/lib/paride-agent/
sudo chown -R root:root /usr/lib/paride-agent
sudo chmod 0755 /usr/lib/paride-agent/paride-agent

2. The configuration

The agent reads server, port and name from /etc/paride-agent/paride-agent.json:

sudo install -d -m 0755 /etc/paride-agent
sudo tee /etc/paride-agent/paride-agent.json > /dev/null <<'EOF'
{"format":1,"server":"build.office","port":PORT,"name":"agent-build1","data_dir":"/var/lib/paride-agent"}
EOF
sudo chmod 0644 /etc/paride-agent/paride-agent.json

Instead of PORT put the number of the server's port, the same the clients use. The name is how the agent introduces itself: letters, digits, dot, dash and underscore. The file holds no secrets.

3. Start and approval

# the service: the paride-agent.service file ships with the program
sudo cp /usr/lib/paride-agent/paride-agent.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable --now paride-agent
sudo tail /var/lib/paride-agent/log/paride-agent.log

On the first start the agent creates its key, introduces itself to the server and waits. Its log shows the command to give on the server, with the 6-digit code:

waiting for the approval of the administrator: on the server run «paride-server user approve agent-build1 326736»

On the server the administrator checks the code and approves:

sudo -u parideserver paride-server user list
sudo -u parideserver paride-server user approve agent-build1 326736
sudo paride-server status          # «agents connected: 1»

A few seconds later the agent is connected, without restarts.

Updating and removing

sudo systemctl stop paride-agent
sudo cp -r paride-agent/. /usr/lib/paride-agent/
sudo chmod 0755 /usr/lib/paride-agent/paride-agent
sudo systemctl start paride-agent

Server first, then the agents. To remove an agent: sudo systemctl disable --now paride-agent, then the service file and /usr/lib/paride-agent; on the server paride-server user remove NAME.

If something goes wrong

The agent stops by itself, and systemd does not restart it, in three cases; the reason is in journalctl -u paride-agent:

  • the configuration is wrong (a port written as text, a name with a space): fix the file and restart;
  • the server refused it: incompatible versions (one of the two must be updated) or a name already used by another machine;
  • the server changed key: if the server was really reinstalled, compare the short code of paride-server status with the one in the agent's log and remove the server's line from /var/lib/paride-agent/hosts.json.

Any other crash makes it restart by itself; and if the server is off the agent waits and retries, without errors.