akhttpd

Documentation

Overview

Command akhttpd is the authorized_keys http daemon. It implements a RESTFUL API which serves authorized_keys files for every GitHub user.

API

This daemon exposes the following API.

GET /
GET /index.html

Returns a human-readable index document.

GET /${username}

When requested from common command line clients, behave like /${username}/authorized_keys. Else, behave like /${username}.html`.

GET /${username}/authorized_keys

Returns an authorized_keys file for the provided username. When successful, returns HTTP 200 along with appropriate Content-Disposition and Content-Type Headers. When the user does not exist, returns HTTP 404. When something goes wrong, returns HTTP 500.

GET /${username}.html

Returns a user-facing page to display keys for the provided username. When successful, returns HTTP 200. When the user does not exist, returns HTTP 404. When something goes wrong, returns HTTP 500.

GET /${username}.sh

Returns a shell script that automatically fills the file '.ssh/authorized_keys' with the keys for the requested user. Any non-existent directories are created. Existing files are overwritten. This script intended to be piped into /bin/sh using a command like

curl http://localhost:8080/username.sh | /bin/sh

When the user does not exist, returns HTTP 404. When something goes wrong, returns HTTP 500.

GET /robots.txt

Returns a robots.txt file.

GET /_/

Optionally serves a static folder for more information and detailed documentation of the current server.

GET /_/upload/

Optionally serves an interface for user uploads.

Configuration

akhttpd can be configured using an environment variable as well as command line arguments.

host:port

By default akhttpd listens on localhost, port 8080 only. To change this, pass an argument of the form 'host:port' to the akhttpd command.

GITHUB_TOKEN=token, -token TOKEN

akhttpd interacts with the GitHub API. By default, this interaction is unauthenticated. Instead a GitHub Personal Access Token can be used. It does not need access to any Scopes. It should be provided using either the GITHUB_TOKEN environment variable or the -token flag.

-api-timeout duration

When interacting with the GitHub API, akhttp uses a default timeout of 1s. After this timeout expires, any response is considered invalid and an HTTP 500 is returned to the client. Use this flag to change the default timeout.

-cache-age duration, -cache-size bytes

To avoid unneccessary GitHub API requests, akhttpd caches responses. Respones are cached for 1h by default, with a maximum cache size of 25kb. Use these flags to change the defaults.

-akpath path

Before querying the GitHub API for a users' public keys first check this path on the filesystem. If a file corresponding to a requested username exists, treat that file as an 'authorized_keys' file and return only keys stored in there.

-index filename

A sensible default index.html file is served on the root directory. Use this flag to select a different file instead.

-serve path

akhttpd can in addition to the standard routes serve a '_' route. Use this flag to configure a directory to be served from this path

-allow-uploads, -upload-auth USER:PASSWORD

akhttpd can optionally allow users to upload their own keys temporarily. This endpoint can also be password protected with the given username and password. The upload-auth can also be provided with the UPLOAD_AUTH environment variable. Providing this variable automatically implies -allow-uploads.

LEGAL_BLOCK=user1,user2

For legal reasons it might be neccessary to block specific users from being served using this service. To block a specific user, use the LEGAL_BLOCK variable. It contains a comma-seperated list of users to be blocked.