uncloud/doc/uncloud-manual-2020-08-01.org

• Bootstrap
• Testing / CLI Access
  • Checkout out the API
  • Authenticate via ldap user in password store
• Database
  • uncloud clients access the data base from a variety of outside hosts
  • So the postgresql data base needs to be remotely accessible
  • Instead of exposing the tcp socket, we make postgresql bind to localhost via IPv6
    • ::1, port 5432
  • Then we remotely connect to the database server with ssh tunneling
    • ssh -L5432:localhost:5432 uncloud-database-host
  • Configuring your database for SSH based remote access
    • host all all ::1/128 trust
• URLs
• Models
  • Bill
  • BillRecord
  • Order
    • Replacing orders
  • Product and Product Children
• Products
  • VPN
    • How to add a new VPN Host
      • Install wireguard to the host
      • Install uncloud to the host
      • Add `python manage.py vpn –hostname fqdn-of-this-host` to the crontab
      • Use the CLI to configure one or more VPN Networks for this host
    • Example of adding a VPN host at ungleich
      • Create a new dual stack alpine VM
      • Add it to DNS as vpn-XXX.ungleich.ch
      • Route a /40 network to its IPv6 address
      • Install wireguard on it
      • Enable wireguard on boot
      • Create a new VPNPool on uncloud with
        • the network address (selecting from our existing pool)
        • the network size (/…)
        • the vpn host that provides the network (selecting the created VM)
        • the wireguard private key of the vpn host (using wg genkey)
        • http command
    • Example http commands / REST calls
      • creating a new vpn pool
      • Creating a new vpn network
• Developer Handbook
  • Identifiers
    • Problem description
    • Approach 1: integers
    • Approach 2: random uuids
    • Approach 3: IPv6 addresses
      • Possible Subnetworks
      • Tests
    • Decision

Bootstrap

• Login via a user so that the user object gets created

• Run the following (replace nicocustomer with the username)

  python manage.py bootstrap-user --username nicocustomer

Testing / CLI Access

Access via the commandline (CLI) can be done using curl or httpie. In our examples we will use httpie.

Checkout out the API

http localhost:8000/api/

Authenticate via ldap user in password store

http --auth nicocustomer:$(pass ldap/nicocustomer)  localhost:8000/api/

Database

uncloud clients access the data base from a variety of outside hosts

So the postgresql data base needs to be remotely accessible

Instead of exposing the tcp socket, we make postgresql bind to localhost via IPv6

::1, port 5432

Then we remotely connect to the database server with ssh tunneling

ssh -L5432:localhost:5432 uncloud-database-host

Configuring your database for SSH based remote access

host all all ::1/128 trust

URLs

• api/ - the rest API

Models

Bill

Bills are summarising usage in a specific timeframe. Bills usually spawn one month.

BillRecord

Bill records are used to model the usage of one order during the timeframe.

Order

Orders register the intent of a user to buy something. They might refer to a product. (???) Order register the one time price and the recurring price. These fields should be treated as immutable. If they need to be modified, a new order that replaces the current order should be created.

Replacing orders

If an order is updated, a new order is created and points to the old order. The old order stops one second before the new order starts.

Product and Product Children

• A product describes something a user can buy
• A product inherits from the uncloud_pay.models.Product model to get basic attributes

Products

VPN

How to add a new VPN Host

Install wireguard to the host

Install uncloud to the host

Add `python manage.py vpn –hostname fqdn-of-this-host` to the crontab

Use the CLI to configure one or more VPN Networks for this host

Example of adding a VPN host at ungleich

Create a new dual stack alpine VM

Add it to DNS as vpn-XXX.ungleich.ch

Route a /40 network to its IPv6 address

Install wireguard on it

TODO Enable wireguard on boot

TODO Create a new VPNPool on uncloud with

the network address (selecting from our existing pool)

the network size (/…)

the vpn host that provides the network (selecting the created VM)

the wireguard private key of the vpn host (using wg genkey)

http command

``` http -a nicoschottelius:$(pass ungleich.ch/nico.schottelius@ungleich.ch) http://localhost:8000/admin/vpnpool/ network=2a0a:e5c1:200:: \ network_size=40 subnetwork_size=48 vpn_hostname=vpn-2a0ae5c1200.ungleich.ch wireguard_private_key=… ```

Example http commands / REST calls

creating a new vpn pool

http -a nicoschottelius:$(pass ungleich.ch/nico.schottelius@ungleich.ch) http://localhost:8000/admin/vpnpool/ network_size=40 subnetwork_size=48 network=2a0a:e5c1:200:: vpn_hostname=vpn-2a0ae5c1200.ungleich.ch wireguard_private_key=$(wg genkey)

Creating a new vpn network

Developer Handbook

The following section describe decisions / architecture of uncloud. These chapters are intended to be read by developers.

Identifiers

Problem description

Identifiers can be integers, strings or other objects. They should be unique.

Approach 1: integers

Integers are somewhat easy to remember, but also include predictable growth, which might allow access to guessed hacking (obivously proper permissions should prevent this).

Approach 2: random uuids

UUIDs are 128 bit integers. Python supports uuid.uuid4() for random uuids.

Approach 3: IPv6 addresses

uncloud heavily depends on IPv6 in the first place. uncloud could use a /48 to identify all objects. Objects that have IPv6 addresses on their own, don't need to draw from the system /48.

Possible Subnetworks

Assuming uncloud uses a /48 to represent all resources.

Network	Name	Description
2001:db8::/48	uncloud network	All identifiers drawn from here
2001:db8:1::/64	VM network	Every VM has an IPv6 address in this network
2001:db8:2::/64	Bill network	Every bill has an IPv6 address
2001:db8:3::/64	Order network	Every order has an IPv6 address
2001:db8:5::/64	Product network	Every product (?) has an IPv6 address
2001:db8:4::/64	Disk network	Every disk is identified

Tests

[15:47:37] black3.place6:~# rbd create -s 10G ssd/2a0a:e5c0:1::8

Decision

We use integers, because they are easy.