docs/storage/gaia-admin.md

description
Storing user data with Blockstack

Use the admin service

{:.no_toc}

A Gaia service can run a simple administrative service co-located with your Gaia hub. This service allows you to administer the Gaia hub with the help of an API key. Gaia hubs installed using the Gaia Amazon Machine Image (AMI) have this service integrated automatically.

In this section, you learn how to use the Gaia admin service with your Gaia hub.

• TOC {:toc}

{% include note.html content=" The examples in this section assume that Gaia and the admin service were installed through the Configure a hub on Amazon EC2." %}

Understand the configuration files

The admin service relies on two configuration files, the hub's configuration and the configuration of the admin service itself. The hub's configuration is mounted /tmp/hub-config/config.json in the docker_admin_1 container. Your EC2 instance has the admin service configuration in the /gaia/docker/admin-config/config.json file.

The admin service needs to know the following:

• where the Gaia hub config file is located
• which API key(s) to use when authenticating administrative requests
• which command(s) to run to restart the Gaia hub on a config change

The following is the standard admin service config installed with your EC2 instance.

{
  "argsTransport": {
    "level": "debug",
    "handleExceptions": true,
    "timestamp": true,
    "stringify": true,
    "colorize": true,
    "json": true
  },
  "port": 8009,
  "apiKeys": [ "hello" ],
  "gaiaSettings": {
    "configPath": "/tmp/hub-config/config.json"
  },
  "reloadSettings": {
    "command": "/bin/sh",
    "argv": [
      "-c",
      "docker restart docker_hub_1 &"
    ],
    "env": {},
    "setuid": 1000,
    "setgid": 1000
  }
}

The port is the port where Gaia is running. The apiKeys field is key used for making calls to the hub. The gaiaSettings

The argsTransport section configures the hub logging. The service uses the winston logging service. Refer to their documentation for full details on the logging configuration options.

Field	Description
level	Lowest level this transport will log. (default: info)
handleException	Set to true to have this transport handle exceptions. (default: false)
timestamp	The timestamp when the message was received.
stringify	Converts the output to a JSON string.
colorize	Colorizes the standard logging level
json	Log format.

The reloadSettings configure the command that is used to reload your Gaia hub.

Field	Description
command	A command which reloads the Gaia hub service.
argv	An array containing the command arguments.
env	This is a key/value list of any environment variables that need to be set for the command to run. This is optional.
setuid	This is the UID under which the command will be run. This is optional.
setgid	This is the GID under which the command will run. This is optional.

Using the admin service APIs

You use the admin service APIs to manage the hub. Administrating a hub requires that you make calls from a terminal on your hub service server. To execute admin functions on a Gaia hub created with AWS, you ssh into your instance as follows:

ssh -t -i <your keyfile.pem> -A core@<public ip address>

You must also set the API_KEY in your environment:

export API_KEY="hello"

You may find it useful to install a JSON processor such as jq to process the output of the admin commands.

Restart the Gaia Hub (POST /v1/admin/reload)

The admin service will make changes to the Gaia hub's config file, but the changes will only take effect when the Gaia hub is reloaded. You can do this as follows:

$ export API_KEY="hello"
$ curl -H "Authorization: bearer $API_KEY" -X POST http://localhost:8009/v1/admin/reload
{"result":"OK"}

When you POST to this endpoint, the admin service runs the command described in the reloadSettings section of the config file. It attempts to spawn a subprocess from the given reloadSettings.command binary, and pass it the arguments given in reloadSettings.argv. Note that the subprocess will NOT be run in a shell.

Errors

{:.no_toc} If you do not supply a valid API key, this method fails with HTTP 403.

This endpoint returns HTTP 500 if the reload command fails. If this happens, you will get back the command's exit code and possibly the signal that killed it.

Get the hub configuration (GET /v1/admin/config)

This endpoint is used to read and write a Gaia hub's non-driver-related settings. These include the port it listens on, and its proof-checking settings.

To read the Gaia hub settings, you would run the following:

$ export API_KEY="hello"
$ curl -H "Authorization: bearer $API_KEY" http://localhost:8009/v1/admin/config {"config":{"port":4000,"proofsConfig":{"proofsRequired":0}}}

Set the hub configuration (POST /v1/admin/config)

To set Gaia hub settings, you simply POST the changed JSON fields to this endpoint.

$ export API_KEY="hello"
$ curl -H "Authorization: bearer $API_KEY" -H 'Content-Type: application/json' -X POST --data-raw '{"port": 3001}' http://localhost:8009/v1/admin/config
{"message":"Config updated -- you should reload your Gaia hub now."}

If the settings were successfully applied, the method returns a message to reload your Gaia hub. You can set multiple drivers' settings with a single call. For example, you can set:

• The driver to use (driver)
• The Gaia's read URL endpoint (readURL)
• The number of items to return when listing files (pageSize)
• The driver-specific settings

The data accepted on POST must contain a valid Hub configuration, for example:

const GAIA_CONFIG_SCHEMA = {
  type: "object",
  properties: {
    validHubUrls: {
      type: "array",
      items: { type: "string", pattern: "^http://.+|https://.+$" },
    },
    requireCorrectHubUrl: { type: "boolean" },
    serverName: { type: "string", pattern: ".+" },
    port: { type: "integer", minimum: 1024, maximum: 65534 },
    proofsConfig: { type: "integer", minimum: 0 },
    whitelist: {
      type: "array",
      items: {
        type: "string",
        pattern: "^[123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz]+$"
      }
    },
    driver: { type: "string", pattern: ".+" },
    readURL: { type: "string", pattern: "^http://.+$|https://.+$" },
    pageSize: { type: "integer", minimum: 1 },
    bucket: { type: "string", pattern: ".+" },
    cacheControl: { type: "string", pattern: ".+" },
    azCredentials: {
      accountName: { type: "string", pattern: ".+" },
      accountKey: { type: "string", pattern: ".+" },
    },
    diskSettings: {
      storageRootDirectory: { type: "string" }
    },
    gcCredentials: {
      email: { type: "string" },
      projectId: { type: "string" },
      keyFilename: { type: "string" },
      credentials: {
        type: "object",
        properties: {
          client_email: { type: "string" },
          private_key: { type: "string" }
        }
      },
    },
    awsCredentials: {
      assessKeyId: { type: "string" },
      secretAccessKey: { type: "string" },
      sessionToken: { type: "string" }
    }
  }
}

The same fields are returned on GET within a config object.

Errors

{:.no_toc} If you do not supply a valid API key, both the GET and POST method fail with HTTP 403.

Only relevant Gaia hub config fields are set. If you POST invalid settings values, you get an HTTP 400 error.

Example: Read and write driver settings

Use the /v1/admin/config endpoint to read and write storage driver settings. To get the current driver settings, you would run:

$ export API_KEY="hello"
$ curl -H "Authorization: bearer $API_KEY" http://localhost:8009/v1/admin/config
{"config":{"driver":"disk","readURL":"http://localhost:4001/","pageSize":20,"diskSettings":{"storageRootDirectory":"/tmp/gaia-disk"}}}

To update the driver settings, you would run:

$ export API_KEY="hello"
$ export AWS_ACCESS_KEY="<hidden>"
$ export AWS_SECRET_KEY="<hidden>"
$ curl -H "Authorization: bearer $API_KEY" -H 'Content-Type: application/json' -X POST --data-raw "{\"driver\": \"aws\", \"awsCredentials\": {\"accessKeyId\": \"$AWS_ACCESS_KEY\", \"secretAccessKey\": \"$AWS_SECRET_KEY\"}}" http://localhost:8009/v1/admin/config
{"message":"Config updated -- you should reload your Gaia hub now."}

Example: Read and write the whitelist

This endpoint lets you read and write the whitelist section of a Gaia hub, to control who can write to it and list its files.

To get the current whitelist, you would run the following:

$ export API_KEY="hello"
$ curl -H "Authorization: bearer $API_KEY" http://localhost:8009/v1/admin/config
{"config":{"whitelist":["15hUKXg1URbQsmaEHKFV2vP9kCeCsT8gUu"]}}

To set the whitelist, you must set the entire whitelist. To set the list, pass a command such as the following:

{% raw %}

$ export API_KEY="hello"
$ curl -H "Authorization: bearer $API_KEY" -H 'Content-Type: application/json' -X POST --data-raw '{"whitelist": ["1KDcaHsYJqD7pwHtpDn6sujCVQCY2e1ktw", "15hUKXg1URbQsmaEHKFV2vP9kCeCsT8gUu"]}' http://localhost:8009/v1/admin/config
{"message":"Config updated -- you should reload your Gaia hub now."}

{% endraw %}

View logs for the hub or admin service

The logs for each Gaia service are maintained by their respective Docker containers. To view the log for a particular service, use the docker logs command. For example, to get the logs for the hub:

$ docker logs docker_hub_1  

> gaia-hub@2.3.4 start /src/hub
> npm run build && node lib/index.js


> gaia-hub@2.3.4 build /src/hub
> npm run lint && babel src -d lib && chmod +x lib/index.js


> gaia-hub@2.3.4 lint /src/hub
> eslint src

Successfully compiled 13 files with Babel.
{"level":"warn","message":"Listening on port 3000 in development mode","timestamp":"2019-02-14T04:00:06.071Z"}