# Administration

## Overview

This document provides an overview of the administration tasks and responsibilities for managing the
system. It includes guidelines for user management, system configuration, and maintenance tasks.

Interactions with the server are done through the `dsfxctl` command line tool, which allows administrators
to perform various operations with their system.

---

## dsfxctl

### Installation

To install the `dsfxctl` command line tool, we recommend using the standard go toolchain to install
the latest version of the tool. You can do this by running the following command:

```bash
go install koti.casa/numenor-labs/dsfx/cmd/dsfxctl@latest
```

### Configuration

The first time you run the `dsfxctl` command, it will create a configuration directory to store
the necessary files for the tool to function properly. By default, this directory is located in the
`/etc/dsfxctl`, but this can be overridden by setting the `DSFXCTL_CONFIG_DIR` environment variable
to a different path. We recommend configuring a path in your home directory so that the command
can be run without root privileges. For example, you can set the environment variable to point
to a directory in your home directory, such as `~/.config/dsfxctl`.

```bash
export DSFXCTL_CONFIG_DIR=~/.config/dsfxctl
```

### Identity

The `dsfxctl` command requires a user identity to perform operations. This identity is specified
by the `ed25519.key` file in the configuration directory. The key file should contain a valid
ed25519 private key encoded in base64. The server application will use this key to sign requests and
authenticate the user. If the key file is not present, which is the case when you first run the command,
the server will generate a new key pair and store it in the `ed25519.key` file. This file is stored
unencrypted, so it is important to ensure that the permissions on this file are set correctly to
prevent unauthorized access. We recommend setting the permissions to `0600` to restrict access
to the owner only. You can do this by running the following command:

```bash
chmod 0600 ~/.config/dsfxctl/ed25519.key
```

In the future we will explore options for encrypting the key at rest, or using a hardware security
module (HSM) to manage the key securely.

To view the identity associated with the `dsfxctl` command, you can run the following command:

```bash
dsfxctl identity
```

This will display the base64 encoded public key associated with the private key in the `ed25519.key` file.

### Admin Registration

Admin registration is performed similar to authorized ssh users. The server application initializes a
file in the config directory called `admins`. This file contains a list of base64 encoded public keys
for each admin user. The server will check this file to determine if a user is authorized to perform
administrative tasks. Keys are separated by newlines, and the server will ignore any empty lines.

You must have access to the host machine that you are deploying the server on to perform the
initial registration of the admin user. You can get the public key of your `dsfxctl` client by running
the `dsfxctl identity` command. You should then copy the base64 encoded public key and paste it into the
`admins` file in the configuration directory.

## User Management

**todo**