caida/ark repository overview

A container based client for the Archipelago⁠ active measurement project. This container will run the team-probing, topo-v6, and fireball activities.

⁠Running

You will need to create an account at https://arkmon.caida.org⁠ in order to register your node before you can run it. After registering your node you will receive an authentication token that you can provide as the ARK_AUTH_TOKEN environment variable when running the container.

The container should always fetch new images before starting, so that it is kept up to date.

A persistent volume is useful to store the ark configuration and the certificates in /etc/ark/, but not strictly required. Without that, new certificates will need to be signed and fetched every time the container is started.

The container sends measurement probes over raw sockets, so ensure you set the NET_RAW capability if your container runtime doesn't do that by default.

⁠Using a systemd service

An easy way to run and manage the ark docker container is to wrap it in a systemd service. You can place a service file that looks something like this in /etc/systemd/system/ark.service:

[Unit]
Description=CAIDA Ark Docker Container
After=network-online.target docker.service
Requires=docker.service

[Service]
User=root
Restart=always
# Depending on trust model you can provide the ARK_AUTH_TOKEN variable here,
# in a file, or soon using systemd credentials
#Environment="ARK_AUTH_TOKEN=XXX"
#EnvironmentFile=/etc/ark/env
#LoadCredential=ARK_AUTH_TOKEN:/etc/ark/token
ExecStartPre=-/usr/bin/docker stop ark
ExecStartPre=-/usr/bin/docker rm ark
ExecStartPre=/usr/bin/docker pull caida/ark:latest
ExecStart=/usr/bin/docker run                    \
            --name ark                           \
            --env ARK_AUTH_TOKEN=$ARK_AUTH_TOKEN \
            --volume ark-volume:/etc/ark/        \
            caida/ark:latest
ExecStop=/usr/bin/docker stop ark

[Install]
WantedBy=multi-user.target

then reload systemd, enable the service, and start it:

sudo systemctl daemon-reload
sudo systemctl enable --now ark.service

⁠Using kubernetes

The following yaml snippet should hopefully be a good starting point for you to use with your own kubernetes cluster:

---
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: ark-volume
spec:
  accessModes:
    - ReadWriteOnce
  resources:
    requests:
      storage: 1Gi


---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: ark
  labels:
    app: ark
spec:
  replicas: 1
  strategy:
    type: Recreate
  selector:
    matchLabels:
      app: ark
  template:
    metadata:
      labels:
        app: ark
    spec:
      restartPolicy: Always
      containers:
        - name: ark
          image: caida/ark:latest
          imagePullPolicy: Always
          resources:
            limits:
              cpu: "2"
              memory: "1Gi"
            requests:
              cpu: "100m"
              memory: "200Mi"
          env:
            - name: ARK_AUTH_TOKEN
              valueFrom:
                secretKeyRef:
                  name: ark-auth
                  key: ARK_AUTH_TOKEN
          volumeMounts:
            - name: ark-volume
              mountPath: /etc/ark/
      volumes:
        - name: ark-volume
          persistentVolumeClaim:
            claimName: ark-volume

And in the simple case you could deploy it with something like:

kubectl create namespace ark
kubectl -n ark create secret generic ark-auth --from-literal=ARK_AUTH_TOKEN='<auth-token>'
kubectl -n ark apply -f ark.yaml

⁠Environment Variables

ARK_AUTH_TOKEN must be set, otherwise the container will not run. Other variables can optionally be set to control specific behavior. Depending on your environment you may want to put it in an env file, or protect it using a docker or kubernetes secret rather than specifying it directly in the systemd service file.

⁠Updating

In order for the container to remain functional and useful, it must be able to receive security, performance, and capability updates. This means that the container must use the image tagged :latest, and must check for updates regularly (preferably each time the container is started). The container will terminate itself when it is ready for an update and expects to be automatically restarted with the newest image that is currently available.

If you are running in a larger kubernetes deployment and followed the example above then you are probably already doing that (e.g. imagePullPolicy: Always).

If you are running the ark container as a systemd service and have configured it like the example to pull the latest image before starting (e.g. ExecStartPre=/usr/bin/docker pull caida/ark:latest) then that should be sufficient.

Alternatively, you might want to try something like watchtower⁠.