Changeset View
Changeset View
Standalone View
Standalone View
src/docs/user/cluster/cluster_devices.diviner
@title Cluster: Devices | @title Cluster: Devices | ||||
@group cluster | @group cluster | ||||
Guide to configuring hosts to act as cluster devices. | Guide to configuring hosts to act as cluster devices. | ||||
Cluster Context | Cluster Context | ||||
=============== | =============== | ||||
This document describes a step in configuring Phabricator to run on | This document describes a step in configuring Phorge to run on | ||||
multiple hosts in a cluster configuration. This is an advanced feature. For | multiple hosts in a cluster configuration. This is an advanced feature. For | ||||
more information on clustering, see @{article:Clustering Introduction}. | more information on clustering, see @{article:Clustering Introduction}. | ||||
In this context, device configuration is mostly relevant to configuring | In this context, device configuration is mostly relevant to configuring | ||||
repository services in a cluster. You can find more details about this in | repository services in a cluster. You can find more details about this in | ||||
@{article:Cluster: Repositories}. | @{article:Cluster: Repositories}. | ||||
Show All 15 Lines | |||||
knows which device it is explicitly. | knows which device it is explicitly. | ||||
Today, this is primarily necessary when configuring repository clusters. | Today, this is primarily necessary when configuring repository clusters. | ||||
Using Almanac | Using Almanac | ||||
============= | ============= | ||||
The tool Phabricator uses to manage cluster devices is the **Almanac** | The tool Phorge uses to manage cluster devices is the **Almanac** | ||||
application, and most configuration will occur through the application's web | application, and most configuration will occur through the application's web | ||||
UI. If you are not familiar with it, see @{article:Almanac User Guide} first. | UI. If you are not familiar with it, see @{article:Almanac User Guide} first. | ||||
This document assumes you are familiar with Almanac concepts. | This document assumes you are familiar with Almanac concepts. | ||||
What Lies Ahead | What Lies Ahead | ||||
=============== | =============== | ||||
Here's a brief overview of the steps required to register cluster devices. The | Here's a brief overview of the steps required to register cluster devices. The | ||||
remainder of this document walks through these points in more detail. | remainder of this document walks through these points in more detail. | ||||
- Create an Almanac device record for each device. | - Create an Almanac device record for each device. | ||||
- Generate, add, and trust SSH keys if necessary. | - Generate, add, and trust SSH keys if necessary. | ||||
- Install Phabricator on the host. | - Install Phorge on the host. | ||||
- Use `bin/almanac register` from the host to register it as a device. | - Use `bin/almanac register` from the host to register it as a device. | ||||
See below for guidance on each of these steps. | See below for guidance on each of these steps. | ||||
Individual vs Shared Keys | Individual vs Shared Keys | ||||
========================= | ========================= | ||||
Before getting started, you should choose how you plan to manage device SSH | Before getting started, you should choose how you plan to manage device SSH | ||||
keys. Trust and device identity are handled separately, and there are two ways | keys. Trust and device identity are handled separately, and there are two ways | ||||
to set up SSH keys so that devices can authenticate with one another: | to set up SSH keys so that devices can authenticate with one another: | ||||
- you can generate a unique SSH key for each device; or | - you can generate a unique SSH key for each device; or | ||||
- you can generate one SSH key and share it across multiple devices. | - you can generate one SSH key and share it across multiple devices. | ||||
Using **unique keys** allows the tools to do some more sanity/safety checks and | Using **unique keys** allows the tools to do some more sanity/safety checks and | ||||
makes it a bit more difficult to misconfigure things, but you'll have to do | makes it a bit more difficult to misconfigure things, but you'll have to do | ||||
more work managing the actual keys. This may be a better choice if you are | more work managing the actual keys. This may be a better choice if you are | ||||
setting up a small cluster (2-3 devices) for the first time. | setting up a small cluster (2-3 devices) for the first time. | ||||
Using **shared keys** makes key management easier but safety checks won't be | Using **shared keys** makes key management easier but safety checks won't be | ||||
able to catch a few kinds of mistakes. This may be a better choice if you are | able to catch a few kinds of mistakes. This may be a better choice if you are | ||||
setting up a larger cluster, plan to expand the cluster later, or have | setting up a larger cluster, plan to expand the cluster later, or have | ||||
experience with Phabricator clustering. | experience with Phorge clustering. | ||||
Because all cluster keys are all-powerful, there is no material difference | Because all cluster keys are all-powerful, there is no material difference | ||||
between these methods from a security or trust viewpoint. Unique keys are just | between these methods from a security or trust viewpoint. Unique keys are just | ||||
potentially easier to administrate at small scales, while shared keys are | potentially easier to administrate at small scales, while shared keys are | ||||
easier at larger scales. | easier at larger scales. | ||||
Create Almanac Device Records | Create Almanac Device Records | ||||
============================= | ============================= | ||||
For each host you plan to make part of a Phabricator cluster, go to the | For each host you plan to make part of a Phorge cluster, go to the | ||||
{nav Almanac} application and create a **device** record. For guidance on this | {nav Almanac} application and create a **device** record. For guidance on this | ||||
application, see @{article:Almanac User Guide}. | application, see @{article:Almanac User Guide}. | ||||
Add **interfaces** to each device record so Phabricator can tell how to | Add **interfaces** to each device record so Phorge can tell how to | ||||
connect to these hosts. Normally, you'll add one HTTP interface (usually on | connect to these hosts. Normally, you'll add one HTTP interface (usually on | ||||
port 80) and one SSH interface (by default, on port 2222) to each device: | port 80) and one SSH interface (by default, on port 2222) to each device: | ||||
For example, if you are building a two-host repository cluster, you may end | For example, if you are building a two-host repository cluster, you may end | ||||
up with records that look like these: | up with records that look like these: | ||||
- Device: `repo001.mycompany.net` | - Device: `repo001.mycompany.net` | ||||
- Interface: `123.0.0.1:2222` | - Interface: `123.0.0.1:2222` | ||||
- Interface: `123.0.0.1:80` | - Interface: `123.0.0.1:80` | ||||
- Device: `repo002.mycompany.net` | - Device: `repo002.mycompany.net` | ||||
- Interface: `123.0.0.2:2222` | - Interface: `123.0.0.2:2222` | ||||
- Interface: `123.0.0.2:80` | - Interface: `123.0.0.2:80` | ||||
Note that these hosts will normally run two `sshd` ports: the standard `sshd` | Note that these hosts will normally run two `sshd` ports: the standard `sshd` | ||||
which you connect to to operate and administrate the host, and the special | which you connect to to operate and administrate the host, and the special | ||||
Phabricator `sshd` that you connect to to clone and push repositories. | Phorge `sshd` that you connect to to clone and push repositories. | ||||
You should specify the Phabricator `sshd` port, **not** the standard `sshd` | You should specify the Phorge `sshd` port, **not** the standard `sshd` | ||||
port. | port. | ||||
If you're using **unique** SSH keys for each device, continue to the next step. | If you're using **unique** SSH keys for each device, continue to the next step. | ||||
If you're using **shared** SSH keys, create a third device with no interfaces, | If you're using **shared** SSH keys, create a third device with no interfaces, | ||||
like `keywarden.mycompany.net`. This device will just be used as a container to | like `keywarden.mycompany.net`. This device will just be used as a container to | ||||
hold the trusted SSH key and is not a real device. | hold the trusted SSH key and is not a real device. | ||||
Show All 15 Lines | |||||
the keywarden device from the device detail screen in the Almanac web UI. | the keywarden device from the device detail screen in the Almanac web UI. | ||||
Save the private key for the next step. | Save the private key for the next step. | ||||
Regardless of how many keys you generated, take the key IDs from the tables | Regardless of how many keys you generated, take the key IDs from the tables | ||||
in the web UI and run this command from the command line for each key, to mark | in the web UI and run this command from the command line for each key, to mark | ||||
each key as trusted: | each key as trusted: | ||||
``` | ``` | ||||
phabricator/ $ ./bin/almanac trust-key --id <key-id-1> | phorge/ $ ./bin/almanac trust-key --id <key-id-1> | ||||
phabricator/ $ ./bin/almanac trust-key --id <key-id-2> | phorge/ $ ./bin/almanac trust-key --id <key-id-2> | ||||
... | ... | ||||
``` | ``` | ||||
The warnings this command emits are serious. The private keys are now trusted, | The warnings this command emits are serious. The private keys are now trusted, | ||||
and allow any user or device possessing them to sign requests that bypass | and allow any user or device possessing them to sign requests that bypass | ||||
policy checks without requiring additional credentials. Guard them carefully! | policy checks without requiring additional credentials. Guard them carefully! | ||||
If you need to revoke trust for a key later, use `untrust-key`: | If you need to revoke trust for a key later, use `untrust-key`: | ||||
``` | ``` | ||||
phabricator/ $ ./bin/almanac untrust-key --id <key-id> | phorge/ $ ./bin/almanac untrust-key --id <key-id> | ||||
``` | ``` | ||||
Once the keys are trusted, continue to the next step. | Once the keys are trusted, continue to the next step. | ||||
Install Phabricator | Install Phorge | ||||
=================== | =================== | ||||
If you haven't already, install Phabricator on each device you plan to enroll | If you haven't already, install Phorge on each device you plan to enroll | ||||
in the cluster. Cluster repository devices must provide services over both HTTP | in the cluster. Cluster repository devices must provide services over both HTTP | ||||
and SSH, so you need to install and configure both a webserver and a | and SSH, so you need to install and configure both a webserver and a | ||||
Phabricator `sshd` on these hosts. | Phorge `sshd` on these hosts. | ||||
Generally, you will follow whatever process you otherwise use when installing | Generally, you will follow whatever process you otherwise use when installing | ||||
Phabricator. | Phorge. | ||||
NOTE: Do not start the daemons on the new devices yet. They won't work properly | NOTE: Do not start the daemons on the new devices yet. They won't work properly | ||||
until you've finished configuring things. | until you've finished configuring things. | ||||
Once Phabricator is installed, you can enroll the devices in the cluster by | Once Phorge is installed, you can enroll the devices in the cluster by | ||||
registering them. | registering them. | ||||
Register Devices | Register Devices | ||||
================ | ================ | ||||
To register a host as an Almanac device, use `bin/almanac register`. | To register a host as an Almanac device, use `bin/almanac register`. | ||||
Show All 33 Lines | $ ./bin/almanac register \ | ||||
--identify-as repo001.mycompany.net | --identify-as repo001.mycompany.net | ||||
``` | ``` | ||||
In particular, note that `--device` is always the **trusted** device associated | In particular, note that `--device` is always the **trusted** device associated | ||||
with the trusted key. The `--identify-as` flag allows several different hosts | with the trusted key. The `--identify-as` flag allows several different hosts | ||||
to share the same key but still identify as different devices. | to share the same key but still identify as different devices. | ||||
The overall effect of the `bin/almanac` command is to copy identity and key | The overall effect of the `bin/almanac` command is to copy identity and key | ||||
files into `phabricator/conf/keys/`. You can inspect the results by examining | files into `phorge/conf/keys/`. You can inspect the results by examining | ||||
that directory. The helper script just catches potential mistakes and makes | that directory. The helper script just catches potential mistakes and makes | ||||
sure the process is completed correctly. | sure the process is completed correctly. | ||||
Note that a copy of the active private key is stored in the `conf/keys/` | Note that a copy of the active private key is stored in the `conf/keys/` | ||||
directory permanently. | directory permanently. | ||||
When converting a host into a cluster host, you may need to revisit | When converting a host into a cluster host, you may need to revisit | ||||
@{article:Diffusion User Guide: Repository Hosting} and double check the `sudo` | @{article:Diffusion User Guide: Repository Hosting} and double check the `sudo` | ||||
Show All 13 Lines |
Content licensed under Creative Commons Attribution-ShareAlike 4.0 (CC-BY-SA) unless otherwise noted; code licensed under Apache 2.0 or other open source licenses. · CC BY-SA 4.0 · Apache 2.0