diff --git a/docs/Concepts/Node-Keys.md b/docs/Concepts/Node-Keys.md index 130a1293ab2..713d9816111 100644 --- a/docs/Concepts/Node-Keys.md +++ b/docs/Concepts/Node-Keys.md @@ -43,8 +43,8 @@ Specified by the [`--p2p-host`](../Reference/CLI/CLI-Syntax.md#p2p-host) and The enode is displayed when starting a Besu node and can be obtained using the [`net_enode`](../Reference/API-Methods.md#net_enode) JSON-RPC API method. -If [UPnP](../HowTo/Find-and-Connect/Using-UPnP.md) is enabled, the enode advertised to other nodes during discovery is the -external IP address and port. +The enode advertised to other nodes during discovery is the external IP address and port, as defined +by [`--nat-method`](../HowTo/Find-and-Connect/Specifying-NAT.md). ## Specifying a Custom Node Private Key File diff --git a/docs/HowTo/Find-and-Connect/Configuring-Ports.md b/docs/HowTo/Find-and-Connect/Configuring-Ports.md index ee88e18dd04..7f1689ca124 100644 --- a/docs/HowTo/Find-and-Connect/Configuring-Ports.md +++ b/docs/HowTo/Find-and-Connect/Configuring-Ports.md @@ -11,7 +11,7 @@ Hyperledger Besu node on AWS is: When running Besu from the [Docker image](../Get-Started/Run-Docker-Image.md), [expose ports](../Get-Started/Run-Docker-Image.md#exposing-ports). !!! tip - Besu supports [UPnP](Using-UPnP.md) for home or small office environments where a wireless router + Besu supports [UPnP](Specifying-NAT.md) for home or small office environments where a wireless router or modem provides NAT isolation. ## P2P Networking diff --git a/docs/HowTo/Find-and-Connect/Specifying-NAT.md b/docs/HowTo/Find-and-Connect/Specifying-NAT.md new file mode 100644 index 00000000000..cd9f1a37dad --- /dev/null +++ b/docs/HowTo/Find-and-Connect/Specifying-NAT.md @@ -0,0 +1,64 @@ +description: Configuring NAT with Hyperledger Besu + + +# Configuring NAT + +Use the [`--nat-method`](../../Reference/CLI/CLI-Syntax.md#nat-method) option to specify the +NAT method. Options are: `UPNP`, `MANUAL`, `DOCKER`, `AUTO`, and `NONE`. + +The [enode](../../Concepts/Node-Keys.md#enode-url) advertised to other nodes during discovery is the +external IP address and port. The [`admin_nodeInfo`](../../Reference/API-Methods.md#admin_nodeinfo) +JSON-RPC API method returns the external address and port for the `enode` and `listenAddr` properties. + +While Hyperledger Besu is running, the following are not supported: + +* IP address changes +* Changing NAT methods. To change the NAT method, restart the node with the [`--nat-method`](../../Reference/CLI/CLI-Syntax.md#nat-method) +option set. + +## UPnP + +Specify `UPNP` to quickly allow inbound peer connections without manual router configuration. Use UPnP +in home or small office environments where a wireless router or modem provides NAT isolation. + +UPnP automatically detects if a node is running in a UPnP environment and provides port forwarding. +UPnP might introduce delays during node startup, especially on networks where no UPnP gateway device can be found. + +!!! tip + UPnP support is often disabled by default in networking firmware. If disabled by default, you must + explicitly enable UPnP support. + +## Manual + +Specify `MANUAL` to explicitly configure the external IP address and ports to advertise. + +When `MANUAL` is specified: + +* [`--p2p-host`](../../Reference/CLI/CLI-Syntax.md#p2p-host) and [`--p2p-port`](../../Reference/CLI/CLI-Syntax.md#p2p-port) +define the advertised host and port for the P2P service. +* [`--rpc-http-host`](../../Reference/CLI/CLI-Syntax.md#rpc-http-host) and [`rpc-http-port`](../../Reference/CLI/CLI-Syntax.md#rpc-http-port) +define the advertised host and port for the JSON-RPC service. + +## Docker + +Specify `DOCKER` to explicitly specify Hyperledger Besu is running inside a Docker container. +When `DOCKER` is specified, the host IP address is advertised not the container IP address. + +The host IP is the advertised host specified in the [`docker run` command](https://docs.docker.com/engine/reference/commandline/run/#add-entries-to-container-hosts-file---add-host). +If not specified in the `docker run` command, the advertised host defaults to [`--p2p-host`](../../Reference/CLI/CLI-Syntax.md#p2p-host) +and [`--p2p-port`](../../Reference/CLI/CLI-Syntax.md#p2p-port). + +## Auto + +`AUTO` is the default NAT method. `AUTO` detects if Besu is running inside Docker container. If +inside a Docker container, acts as if [`DOCKER`](#docker) is specified. Otherwise, acts as if +[`NONE`](#none) is specified. + +## None + +Specify `NONE` to explicitly specify Besu does not use NAT. If the NAT method is `NONE` and [`--p2p-host`](../../Reference/CLI/CLI-Syntax.md#p2p-host), +[`--p2p-port`](../../Reference/CLI/CLI-Syntax.md#p2p-port), [`--rpc-http-host`](../../Reference/CLI/CLI-Syntax.md#rpc-http-host), +and [`rpc-http-port`](../../Reference/CLI/CLI-Syntax.md#rpc-http-port) are specified, they are +ignored in the advertised addresses and the default values are advertised. + + diff --git a/docs/HowTo/Find-and-Connect/Using-UPnP.md b/docs/HowTo/Find-and-Connect/Using-UPnP.md deleted file mode 100644 index 4d4d95deee8..00000000000 --- a/docs/HowTo/Find-and-Connect/Using-UPnP.md +++ /dev/null @@ -1,33 +0,0 @@ -description: Configuring UPnP with Hyperledger Besu - - -# UPnP - -Enable UPnP to quickly allow inbound peer connections without manual router configuration. Use UPnP -in home or small office environments where a wireless router or modem provides NAT isolation. - -UPnP automatically detects that a node is running in a UPnP environment and provides port forwarding. - -!!! tip - UPnP support is often disabled by default in networking firmware. If disabled by default, explicitly - enable UPnP support. - -## Enabling UPnP - -Use the [`--nat-method`](../../Reference/CLI/CLI-Syntax.md#nat-method) command line option to enable UPnP. - -!!! notes - * Option `UPNP` might introduce delays during node startup, especially on networks where no UPnP gateway device can be found. - * `--nat-method` cannot be used with the [Besu Docker image](../../HowTo/Get-Started/Run-Docker-Image.md). - -When UPnP is enabled: - -* [Enode](../../Concepts/Node-Keys.md#enode-url) advertised to other nodes during discovery is the external IP address and port. -* External address and port are returned by the [`admin_NodeInfo`](../../Reference/API-Methods.md#admin_nodeinfo) - JSON-RPC API method for the `enode` and `listenAddr` properties. - -While Hyperledger Besu is running, UPnP does not support: - -* IP address changes -* Disabling UPnP. To disable UPnP, restart the node without the [`--nat-method`](../../Reference/CLI/CLI-Syntax.md#nat-method) -option or set to `NONE`. \ No newline at end of file diff --git a/docs/HowTo/Get-Started/Run-Docker-Image.md b/docs/HowTo/Get-Started/Run-Docker-Image.md index 51d979c1dc0..bd98c0b8f2f 100644 --- a/docs/HowTo/Get-Started/Run-Docker-Image.md +++ b/docs/HowTo/Get-Started/Run-Docker-Image.md @@ -57,7 +57,11 @@ docker run -p :8545 -p :8546 -p :3 data path interferes with the operation of Besu and prevents Besu from safely launching. To run a node that maintains the node state (key and database), [`--data-path`](../../Reference/CLI/CLI-Syntax.md#data-path) - must be set to a location other than `/opt/besu` and a storage volume mounted at that location. + must be set to a location other than `/opt/besu` and a storage volume mounted at that location. + + When running in a Docker container, [`--nat-method`](../Find-and-Connect/Specifying-NAT.md) must + be set to `DOCKER` or `AUTO` (default). Do not set [`--nat-method`](../Find-and-Connect/Specifying-NAT.md) + to `NONE`, `UPNP`, or `MANUAL`. [Besu environment variables](../../Reference/CLI/CLI-Syntax.md#besu-environment-variables) can be specified with the docker image instead of the command line options. diff --git a/docs/Reference/API-Methods.md b/docs/Reference/API-Methods.md index ad8ab1ad55d..34dc8ff45bc 100644 --- a/docs/Reference/API-Methods.md +++ b/docs/Reference/API-Methods.md @@ -176,8 +176,8 @@ Properties of the node object are: !!! note If the node is running locally, the host of the `enode` and `listenAddr` are displayed as `[::]` in the result. - If [UPnP](../HowTo/Find-and-Connect/Using-UPnP.md) is enabled, the external address is - displayed for the `enode` and `listenAddr`. + When advertising externally, the external address displayed for the `enode` and `listenAddr` is + defined by [`--nat-method`](../HowTo/Find-and-Connect/Specifying-NAT.md). !!! example ```bash tab="curl HTTP request" diff --git a/docs/Reference/CLI/CLI-Syntax.md b/docs/Reference/CLI/CLI-Syntax.md index 1aaafed346c..a46ef501056 100644 --- a/docs/Reference/CLI/CLI-Syntax.md +++ b/docs/Reference/CLI/CLI-Syntax.md @@ -745,15 +745,16 @@ Default is 1000. nat-method="UPNP" ``` -Specify the method for handling [NAT environments](../../HowTo/Find-and-Connect/Using-UPnP.md). Options are: `UPNP` and `NONE`. -The default is `NONE`, which disables NAT functionality. +Specify the method for handling [NAT environments](../../HowTo/Find-and-Connect/Specifying-NAT.md). +Options are: [`UPNP`, `MANUAL`, `DOCKER`, `AUTO`, and `NONE`](../../HowTo/Find-and-Connect/Specifying-NAT.md). +The default is `AUTO`. `NONE` disables NAT functionality. !!!tip UPnP support is often disabled by default in networking firmware. If disabled by default, explicitly enable UPnP support. !!!notes * Option `UPNP` might introduce delays during node startup, especially on networks where no UPnP gateway device can be found. - * `--nat-method` cannot be used with the [Besu Docker image](../../HowTo/Get-Started/Run-Docker-Image.md). + * `--nat-method=DOCKER` must be specified when using the [Besu Docker image](../../HowTo/Get-Started/Run-Docker-Image.md). ### network diff --git a/mkdocs.yml b/mkdocs.yml index 0d81a030604..f924d36a87f 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -89,7 +89,7 @@ nav: - Configure Static Nodes: HowTo/Find-and-Connect/Static-Nodes.md - Configure Ports for Access: HowTo/Find-and-Connect/Configuring-Ports.md - Manage Peers: HowTo/Find-and-Connect/Managing-Peers.md - - Use UPnP: HowTo/Find-and-Connect/Using-UPnP.md + - Specify NAT Method: HowTo/Find-and-Connect/Specifying-NAT.md - Monitor Nodes: - Use Metrics: HowTo/Monitor/Metrics.md - Configure Logging: HowTo/Monitor/Logging.md