mirror of
https://git.numenor-labs.us/dsfx.git
synced 2025-04-29 16:20:34 +00:00
78 lines
3.2 KiB
Markdown
78 lines
3.2 KiB
Markdown
# 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**
|