agama/rust/WEB-SERVER.md

Web server development notes

This document includes some notes about the usage and development of Agama's web server.

Installing Rust and related tools

It is recommended to use Rustup to install Rust and related tools. In openSUSE distributions, rustup is available as a package. After rustup is installed, you can proceed to install the toolchain:

zypper --non-interactive in rustup
rustup install stable

In addition to the Rust compiler, the previous command would install some additionall components like cargo, clippy, rustfmt, documentation, etc.

Another interesting addition might be cargo-binstall, which allows to install Rust binaries. If you are fine with this approach, just run:

cargo install cargo-binstall

Setting up PAM

The web sever will use Pluggable Authentication Modules (PAM) for authentication. For that reason, you need to copy the agama service definition for PAM to /usr/lib/pam.d. Otherwise, PAM would not know how to authenticate the service:

cp share/agama.pam /usr/lib/pam.d/agama

For further information, see Authenticating with PAM.

Running the server

Note

The web server needs to connect to Agama's D-Bus daemon. So you can either start the Agama service or just start the D-Bus daemon (sudo bundle exec bin/agamactl -f from the service/ directory).

You need to run the server as root, so you cannot use cargo run directly. Instead, just do:

$ cargo build
$ sudo ./target/debug/agama-web-server serve

If it fails to compile, please check whether clang-devel and pam-devel are installed.

By default the server uses port 80 and listens on all network interfaces. You can use the --address option if you want to use a different port or a specific network interface:

$ sudo ./target/debug/agama-web-server serve --address :::5678

Some more examples:

• Both IPv6 and IPv4, all interfaces: --address :::5678
• Both IPv6 and IPv4, only local loopback : --address ::1:5678
• IPv4 only, all interfaces: --address 0.0.0.0:5678
• IPv4 only, only local loopback : --address 127.0.0.1:5678
• IPv4, only specific interface: --address 192.168.1.2:5678 (use the IP address of that interface)

The server can listen on several addresses, you can use the --address option multiple times.

Trying the server

You can check whether the server is up and running by just performing a ping:

$ curl http://localhost/ping

Authentication

The web server uses a bearer token for HTTP authentication. You can get the token by providing your password to the /auth endpoint.

$ curl http://localhost/api/auth \
    -H "Content-Type: application/json" \
    -d '{"password": "your-password"}' 
{"token":"eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjE3MDg1MTA5MzB9.3HmKAC5u4H_FigMqEa9e74OFAq40UldjlaExrOGqE0U"}⏎

Now you can access protected routes by including the token in the header:

$ curl -X GET http://localhost/protected \
    -H "Accept: application/json" \
    -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjE3MDg1MTA5MzB9.3HmKAC5u4H_FigMqEa9e74OFAq40UldjlaExrOGqE0U"

Connecting to the websocket

You can use websocat to connect to the websocket. To install the tool, just run:

$ cargo binstall websocat

If you did not install cargo-binstall, you can do:

$ cargo install websocat

Now, you can use the following command to connect:

$ websocat ws://localhost/ws
    -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjE3MDg1MTA5MzB9.3HmKAC5u4H_FigMqEa9e74OFAq40UldjlaExrOGqE0U"

SSL/TLS (HTTPS) Support

The web server supports encrypted communication using the HTTPS protocol.

The SSL certificate used by the server can be specified by the --cert and --key command line options which should point to the PEM files:

$ sudo ./target/debug/agama-web-server serve --cert certificate.pem --key key.pem

The certificate is expected in the PEM format, if you have a certificate in another format you can convert it using the openSSL tools.

If a SSL certificate is not specified via command line then the server generates a self-signed certificate. Currently it is only kept in memory and generated again at each start.

The HTTPS protocol is required for external connections, the HTTP connections are automatically redirected to HTTPS. But it still means that the original HTTP communication can be intercepted by an attacker, do not rely on this redirection!

For internal connections coming from the same machine (via the http://localhost URL) the unencrypted HTTP communication is allowed.