From 5defbaf4c4e3da2997fa9950f8c37f04fe898293 Mon Sep 17 00:00:00 2001 From: Jacek Nykis Date: Tue, 17 Dec 2024 17:55:03 +0000 Subject: [PATCH] Update core node documentation * add information about debian package signing * add information about adding apt repo to Ubuntu systems * add list of packages and install instructions * clarify "Network Access" section name to make it explicit this it's specific to the stellar network * refresh various commands and ensure they will work by default on a package based installation --- docs/validators/admin-guide/commands.mdx | 8 ++-- docs/validators/admin-guide/configuring.mdx | 3 +- .../admin-guide/environment-preparation.mdx | 11 ++++++ docs/validators/admin-guide/installation.mdx | 39 +++++++++++++++++-- docs/validators/admin-guide/logging.mdx | 4 +- docs/validators/admin-guide/monitoring.mdx | 22 +++++------ .../admin-guide/network-upgrades.mdx | 4 +- docs/validators/admin-guide/prerequisites.mdx | 2 +- docs/validators/admin-guide/running-node.mdx | 4 +- .../admin-guide/soroban-settings.mdx | 2 +- 10 files changed, 72 insertions(+), 27 deletions(-) diff --git a/docs/validators/admin-guide/commands.mdx b/docs/validators/admin-guide/commands.mdx index ed5eb7b07..60c9e43e3 100644 --- a/docs/validators/admin-guide/commands.mdx +++ b/docs/validators/admin-guide/commands.mdx @@ -20,10 +20,10 @@ Additionally, while the commands on this page are _CLI_ commands, there is an ad The `--help` (aliases: `-h` or `-?`) option can be specified at _any place_ in the command line. It will show you the help message for the relevant command. Some example useage is as follows: ```bash -stellar-core --help -stellar-core run --help -stellar-core --help new-db -stellar-core catchup --help +sudo -u stellar stellar-core --conf /etc/stellar/stellar-core.cfg --help +sudo -u stellar stellar-core --conf /etc/stellar/stellar-core.cfg run --help +sudo -u stellar stellar-core --conf /etc/stellar/stellar-core.cfg --help new-db +sudo -u stellar stellar-core --conf /etc/stellar/stellar-core.cfg catchup --help ``` ## Essential Commands diff --git a/docs/validators/admin-guide/configuring.mdx b/docs/validators/admin-guide/configuring.mdx index af49e996e..f2f2cded8 100644 --- a/docs/validators/admin-guide/configuring.mdx +++ b/docs/validators/admin-guide/configuring.mdx @@ -15,12 +15,13 @@ Before attempting to configure stellar-core, it is highly recommended to first t After you've [installed](./installation.mdx) Stellar Core, your next step is to complete a configuration file that specifies crucial things about your node — like whether it connects to the Testnet or the Mainnet public network, what database it writes to, and which other nodes are in its [quorum set](#choosing-your-quorum-set). -All configuration for stellar-core is done with a [TOML](https://github.com/toml-lang/toml) file. By default, Stellar Core loads that file from `./stellar-core.cfg`, but you can specify a different file to load on the command line: +All configuration for stellar-core is done with a [TOML](https://github.com/toml-lang/toml) file. By default, Stellar Core loads that file from `./stellar-core.cfg` and Debian packages will use the `/etc/stellar/stellar-core.cfg` file. You can specify a different file to load on the command line: ```bash stellar-core --conf betterfile.cfg ``` +When installing using official Debian packages systemd unit file is configured to use `/etc/stellar/stellar-core.cfg` file The examples in these docs don't specify `--conf betterfile.cfg` for the sake of brevity. This page will walk you through the key fields you'll need to include in your config file to get your node up and runninig. diff --git a/docs/validators/admin-guide/environment-preparation.mdx b/docs/validators/admin-guide/environment-preparation.mdx index 9c0aaa9ab..7d6e34ca3 100644 --- a/docs/validators/admin-guide/environment-preparation.mdx +++ b/docs/validators/admin-guide/environment-preparation.mdx @@ -79,6 +79,17 @@ The very first time you want to use your archive, _before starting your node_, y stellar-core new-hist ``` +:::note + +In a secure, production, environment Stellar Core should be run as a dedicated user. Debian packages will ensure the `stellar` user exists on the system. +For this reason you may need to run commands as the stellar user, for example: +```bash +sudo -u stellar stellar-core --conf /etc/stellar/stellar-core.cfg new-hist +``` + +::: + + More detailed guidance and strategies for publishing history archives can be found in the [publishing history archives](./publishing-history-archives.mdx) page. Please check there for more information. :::info IMPORTANT: diff --git a/docs/validators/admin-guide/installation.mdx b/docs/validators/admin-guide/installation.mdx index 3df480a67..747fcc445 100644 --- a/docs/validators/admin-guide/installation.mdx +++ b/docs/validators/admin-guide/installation.mdx @@ -25,9 +25,42 @@ The version number scheme that we follow is `protocol_version.release_number.pat ## Package-Based Installation -If you are using a recent LTS version of Ubuntu, we provide the latest stable releases of [`stellar-core`](https://github.com/stellar/stellar-core) and [`stellar-horizon`](https://github.com/stellar/go/tree/master/services/horizon) in Debian binary package format. +If you are using a recent LTS version of Ubuntu, we provide [`stellar-core`](https://github.com/stellar/stellar-core) and [`stellar-horizon`](https://github.com/stellar/go/tree/master/services/horizon) in Debian binary package format. The packages are cryptographically signed by the Stellar Development Foundation and files can be validated on the system to confirm they were not tampered with. Debian packages utilize operating system built-in cryptographic verification during upgrades which mitigates many supply chain attacks. -You may choose to install these packages individually, which offers the greatest flexibility, but requires **manual** creation of the relevant configuration files and configuration of a **PostgreSQL** database. +SDF package signing key fingerprint is **AEAF 01EE A6CA FCEF DDAE 8AA7 0463 8272 A136 B5A6** (A136B5A6) + +### Configure SDF Apt Repository On The System + +```bash +sudo install -d /etc/apt/keyrings +sudo curl -fsSL https://apt.stellar.org/SDF.asc -o /etc/apt/keyrings/SDF.asc +sudo chmod a+r /etc/apt/keyrings/SDF.asc +echo "deb [signed-by=/etc/apt/keyrings/SDF.asc] https://apt.stellar.org $(lsb_release -cs) stable" | sudo tee -a /etc/apt/sources.list.d/SDF.list +``` + +Optionally you can add testing repository. This is not recommended for production systems but may be useful for non-production systems using testnet: +```bash +echo "deb [signed-by=/etc/apt/keyrings/SDF.asc] https://apt.stellar.org $(lsb_release -cs) stable" | sudo tee -a /etc/apt/sources.list.d/SDF.list +``` + +### Install packages + +We publish multiple packages for convenience. + +| Package | Dependencies | Comments | +| --- | --- | --- | +| stellar-core | none | installs stellar-core binary, systemd service, logrotate script, documentation | +| stellar-core-utils | none | installs useful command line tools (stellar-core-cmd, stellar-core-gap-detect) | +| stellar-core-prometheus-exporter | none | installs a Prometheus exporter to facilitate ingesting stellar-core metrics | +| stellar-core-postgres | stellar-core, PostgreSQL | configures a PostgreSQL server, creates a stellar db,role and system user, the default stellar-core configuration contained in this package will connect to the Testnet| +| stellar-archivist | none | installs stellar-archivist cli tool for managing stellar-core History archives | + +To install a chosen package run: + +```bash +# To install stellar-core +sudo apt-get update && apt-get install +``` ## Installing From Source @@ -65,7 +98,7 @@ docker run -v "/path/to/config/dir:/etc/stellar/" stellar/stellar-core:latest ne docker run -d -v "/path/to/config/dir:/etc/stellar/" stellar/stellar-core:latest run ``` -The image utilizes deb packages so it's possible to confirm the checksum of the `stellar-core` binary in the docker image matches what is in the cryptographically signed deb package. See [packages documentation](https://github.com/stellar/packages/) for information on installing Ubuntu packages. To calculate this checksum in the docker image you can run: +The image utilizes deb packages so it's possible to confirm the checksum of the `stellar-core` binary in the docker image matches what is in the cryptographically signed deb package. See [package based installation section](#package-based-installation) for information. To calculate this checksum in the docker image you can run: ```bash docker run --entrypoint=/bin/sha256sum stellar/stellar-core:latest /usr/bin/stellar-core diff --git a/docs/validators/admin-guide/logging.mdx b/docs/validators/admin-guide/logging.mdx index 36cbead19..e4dff1b78 100644 --- a/docs/validators/admin-guide/logging.mdx +++ b/docs/validators/admin-guide/logging.mdx @@ -14,7 +14,7 @@ Log messages at different priority levels can be color-coded on standard error b The log level can be controlled by configuration, the `--ll` command-line flag, or adjusted dynamically by administrative (HTTP) commands. To do so, run: ```bash -$ stellar-core http-command "ll?level=debug" +sudo -u stellar stellar-core --conf /etc/stellar/stellar-core.cfg http-command "ll?level=debug" ``` while your node is running. @@ -22,7 +22,7 @@ while your node is running. Log levels can also be adjusted on a partition-by-partition basis through the administrative interface. For example the history system can be set to `DEBUG`-level logging by running: ```bash -stellar-core http-command "ll?level=debug&partition=history" +sudo -u stellar stellar-core --conf /etc/stellar/stellar-core.cfg http-command "ll?level=debug&partition=history" ``` Against a running system. diff --git a/docs/validators/admin-guide/monitoring.mdx b/docs/validators/admin-guide/monitoring.mdx index 1c063e9be..bc002b064 100644 --- a/docs/validators/admin-guide/monitoring.mdx +++ b/docs/validators/admin-guide/monitoring.mdx @@ -19,7 +19,7 @@ However you decide to monitor, the most important thing is that you have a syste ## General Node Information -If you run `$ stellar-core http-command 'info'`, the output will look something like this: +If you run `sudo -u stellar stellar-core --conf /etc/stellar/stellar-core.cfg http-command 'info'`, the output will look something like this: ```json { @@ -90,7 +90,7 @@ The `peers` command returns information on the peers your node is connected to. This list is the result of both inbound connections from other peers and outbound connections from this node to other peers. If `compact=false` is used in the command, then it also returns some extra metrics on each peer such as the number of dropped messages. ```bash -stellar-core http-command 'peers' +sudo -u stellar stellar-core --conf /etc/stellar/stellar-core.cfg http-command 'peers' ``` The output will look something like: @@ -233,15 +233,15 @@ In this example, we have three nodes `GBBN`, `GDEX`, and `GBUI` (we'll refer to ```bash # 1. Begin the surveyor collecting phase -stellar-core http-command 'startsurveycollecting?nonce=1234' +sudo -u stellar stellar-core --conf /etc/stellar/stellar-core.cfg http-command 'startsurveycollecting?nonce=1234' # 2. Stop the surveyor collecting phase, and begin the reporting phase -stellar-core http-command 'stopsurveycollecting?nonce=1234' +sudo -u stellar stellar-core --conf /etc/stellar/stellar-core.cfg http-command 'stopsurveycollecting?nonce=1234' # 3. Request survey results from the `GBBN` node -stellar-core http-command 'surveytopologytimesliced?node=GBBNXPPGDFDUQYH6RT5VGPDSOWLZEXXFD3ACUPG5YXRHLTATTUKY42CL&inboundpeerindex=0&outboundpeerindex=0' +sudo -u stellar stellar-core --conf /etc/stellar/stellar-core.cfg http-command 'surveytopologytimesliced?node=GBBNXPPGDFDUQYH6RT5VGPDSOWLZEXXFD3ACUPG5YXRHLTATTUKY42CL&inboundpeerindex=0&outboundpeerindex=0' # 4. Request survey results from the `GDEX` node -stellar-core http-command 'surveytopologytimesliced?node=GDEXJV6XKKLDUWKTSXOOYVOYWZGVNIKKQ7GVNR5FOV7VV5K4MGJT5US4&inboundpeerindex=0&outboundpeerindex=0' +sudo -u stellar stellar-core --conf /etc/stellar/stellar-core.cfg http-command 'surveytopologytimesliced?node=GDEXJV6XKKLDUWKTSXOOYVOYWZGVNIKKQ7GVNR5FOV7VV5K4MGJT5US4&inboundpeerindex=0&outboundpeerindex=0' # 3. Retrieve and display the results of issued survey commands -stellar-core http-command 'getsurveyresult' +sudo -u stellar stellar-core --conf /etc/stellar/stellar-core.cfg http-command 'getsurveyresult' ``` Once the responses are received, the `getsurveyresult` command will return a result like this: @@ -350,7 +350,7 @@ The `quorum` command allows you to diagnose problems with the quorum set of the If you run: ```bash -stellar-core http-command 'quorum' +sudo -u stellar stellar-core --conf /etc/stellar/stellar-core.cfg http-command 'quorum' ``` The output will look something like: @@ -429,9 +429,9 @@ You can get a sense of the quorum set health of a different node using using: ```bash # the `NAME` of a validator -stellar-core http-command 'quorum?node=$sdf1' +sudo -u stellar stellar-core --conf /etc/stellar/stellar-core.cfg http-command 'quorum?node=$sdf1' # OR the `PUBLIC_KEY` of a validator -stellar-core http-command 'quorum?node=@GABCDE' +sudo -u stellar stellar-core --conf /etc/stellar/stellar-core.cfg http-command 'quorum?node=@GABCDE' ``` Overall network health can be evaluated by walking through all nodes and looking at their health. Note that this is only an approximation, as remote nodes may not have received the same messages (in particular: `missing` for other nodes is not reliable). @@ -452,7 +452,7 @@ When showing quorum-set information about the local node rather than some other The quorum endpoint can also retrieve detailed information about the transitive quorum. This is a format that's easier to process than what `scp` returns, as it doesn't contain all SCP messages. ```bash -stellar-core http-command 'quorum?transitive=true' +sudo -u stellar stellar-core --conf /etc/stellar/stellar-core.cfg http-command 'quorum?transitive=true' ``` The output looks something like: diff --git a/docs/validators/admin-guide/network-upgrades.mdx b/docs/validators/admin-guide/network-upgrades.mdx index 86a3e6556..349938cf9 100644 --- a/docs/validators/admin-guide/network-upgrades.mdx +++ b/docs/validators/admin-guide/network-upgrades.mdx @@ -52,9 +52,9 @@ By way of example, here is the `upgrades` command used to upgrade the protocol v ```bash # arm the node to vote for the upgrade -stellar-core http-command 'upgrades?mode=set&upgradetime=2018-01-31T20:00:00Z&protocolversion=9' +sudo -u stellar stellar-core --conf /etc/stellar/stellar-core.cfg http-command 'upgrades?mode=set&upgradetime=2018-01-31T20:00:00Z&protocolversion=9' # view the status of the node -stellar-core http-command info +sudo -u stellar stellar-core --conf /etc/stellar/stellar-core.cfg http-command info ``` At this point `info` will tell you that the node is setup to vote for this upgrade: diff --git a/docs/validators/admin-guide/prerequisites.mdx b/docs/validators/admin-guide/prerequisites.mdx index abaab5d32..d8a305dec 100644 --- a/docs/validators/admin-guide/prerequisites.mdx +++ b/docs/validators/admin-guide/prerequisites.mdx @@ -23,7 +23,7 @@ Stellar Core is designed to run on relatively modest hardware so that a whole ra _\* Assuming a 30-day retention window for data storage._ -## Network Access +## Stellar Network Access Stellar Core interacts with the peer-to-peer network to keep a distributed ledger in sync, which means that your node needs to make certain [TCP ports](https://en.wikipedia.org/wiki/Transmission_Control_Protocol#TCP_ports) available for inbound and outbound communication. diff --git a/docs/validators/admin-guide/running-node.mdx b/docs/validators/admin-guide/running-node.mdx index 8d5145df0..c3ccf8dfe 100644 --- a/docs/validators/admin-guide/running-node.mdx +++ b/docs/validators/admin-guide/running-node.mdx @@ -10,7 +10,7 @@ Once you've [set up your environment](./prerequisites.mdx), [configured your nod Use a command equivalent to: ```bash -stellar-core run +sudo systemctl start stellar-core ``` At this point, you're ready to observe your core node's activity as it joins the network. @@ -22,7 +22,7 @@ You may want to skip ahead and review the [Logging](./logging.mdx) page to famil When your node is running, you can interact with Stellar Core via an administrative HTTP endpoint. Commands can be issued using command-line HTTP tools such as `curl`, or by running a CLI command such as ```bash -stellar-core http-command +sudo -u stellar stellar-core --conf /etc/stellar/stellar-core.cfg http-command ``` The HTTP endpoint is [not intended to be exposed to the public internet](./prerequisites.mdx#internal-system-access). It's typically accessed by administrators, or by a mid-tier application to submit transactions to the Stellar network. diff --git a/docs/validators/admin-guide/soroban-settings.mdx b/docs/validators/admin-guide/soroban-settings.mdx index 3ff065f85..e3d59614e 100644 --- a/docs/validators/admin-guide/soroban-settings.mdx +++ b/docs/validators/admin-guide/soroban-settings.mdx @@ -69,7 +69,7 @@ You're required to provide four arguments for this command: For example, the command for the phase 2 upgrade might have looked like this: ```bash -stellar-core get-settings-upgrade-txs \ +sudo -u stellar stellar-core --conf /etc/stellar/stellar-core.cfg get-settings-upgrade-txs \ GAUQW73V52I2WLIPKCKYXZBHIYFTECS7UPSG4OSVUHNDXEZJJWFXZG56 \ 73014444032 \ "Public Global Stellar Network ; September 2015" \