OSDOCS-1496 - Advanced networking tables

modules/installation-user-infra-machines-static-network.adoc

@@ -2,22 +2,37 @@
 //
 // * installing/installing_bare_metal/installing-bare-metal.adoc
 // * installing/installing_bare_metal/installing-restricted-networks-bare-metal.adoc
-// * installing_bare_metal/installing-bare-metal-network-customizations.adoc
+// * installing/installing_bare_metal/installing-bare-metal-network-customizations.adoc
 
 [id="installation-user-infra-machines-static-network_{context}"]
-= Configure advanced networking
+= Advanced {op-system} installation reference
 
-If you install {op-system-first} from an ISO image, you can add kernel arguments
-when you boot that image to configure the node's networking.
-The following table describes and illustrates how to use those kernel arguments.
+This section illustrates the networking configuration and other advanced options that allow you to modify the {op-system-first} bare metal install process. The following tables describe the kernel arguments and command-line options you can use with:
 
-.Configure advanced networking
+* The {op-system} live installer boot prompt by using routing and bonding.
+
+* The {op-system} live installer by using `core.inst` for ISO or PXE installs.
+
+* The `coreos-installer` command for ISO installs.
+
+[discrete]
+== Routing and bonding options at {op-system} boot prompt
+
+If you install {op-system} from an ISO image, you can add kernel arguments manually when you boot that image to configure the node's networking. If no networking arguments are used, the installation defaults to using DHCP.
+
+[IMPORTANT]
+====
+When adding networking arguments, you must also add the `rd.neednet=1` kernel argument.
+====
+
+The following table describes how to use `ip=`, `nameserver=`, and `bond=` kernel arguments for live ISO installs.
+
+.Routing and bonding options for ISO
 [source,adoc]
 |===
 |Description |Examples
 
-a|To configure an IP address, either use DHCP (`ip=dhcp`) or set an individual
-static IP address (`ip=<host_ip>`). Then identify the DNS server IP address (`nameserver=<dns_ip>`) on each node. This example sets: +
+a|To configure an IP address, either use DHCP (`ip=dhcp`) or set an individual static IP address (`ip=<host_ip>`). Then identify the DNS server IP address (`nameserver=<dns_ip>`) on each node. This example sets: +
 
 * The node's IP address to `10.10.10.2` +
 * The gateway address to `10.10.10.254` +
@@ -31,40 +46,41 @@ ip=10.10.10.2::10.10.10.254:255.255.255.0:core0.example.com:enp1s0:none
 nameserver=4.4.4.41
 ----
 
-|Specify multiple network interfaces by specifying multiple `ip=` entries.
+a|Specify multiple network interfaces by specifying multiple `ip=` entries.
+
 a|
 ----
 ip=10.10.10.2::10.10.10.254:255.255.255.0:core0.example.com:enp1s0:none
 ip=10.10.10.3::10.10.10.254:255.255.255.0:core0.example.com:enp2s0:none
 ----
 
-|You can combine DHCP
-and static IP configurations on systems with
-multiple network interfaces.
+a|You can combine DHCP and static IP configurations on systems with multiple network interfaces.
+
 a|
 ----
 ip=enp1s0:dhcp
 ip=10.10.10.2::10.10.10.254:255.255.255.0:core0.example.com:enp2s0:none
 ----
 
-|You can provide multiple DNS servers by adding a `nameserver=` entry for each server.
+a|You can provide multiple DNS servers by adding a `nameserver=` entry for each server.
+
 a|
 ----
 nameserver=1.1.1.1
 nameserver=8.8.8.8
 ----
 
-a|Bonding multiple network interfaces to a single interface is optionally supported
-using the `bond=` option.  In these two examples:
+a|Optional: Bonding multiple network interfaces to a single interface is supported using the `bond=` option. In these two examples:
 
 * The syntax for configuring a bonded interface is: `bond=name[:network_interfaces][:options]`
 * _name_ is the bonding device name (`bond0`), _network_interfaces_
 represents a comma-separated list of physical (ethernet) interfaces (`em1,em2`),
-and _options_ is a comma-separated list of bonding options. (Enter `modinfo bonding` to see available options.)
+and _options_ is a comma-separated list of bonding options. Enter `modinfo bonding` to see available options.
 * When you
 create a bonded interface using `bond=`, you must specify how the IP address
 is assigned and other
 information for the bonded interface.
+
 a|
 To configure the bonded interface to use DHCP, set the bond's IP address
 to `dhcp`. For example:
@@ -81,4 +97,199 @@ enter the specific IP address you want and related information. For example:
 bond=bond0:em1,em2:mode=active-backup
 ip=10.10.10.2::10.10.10.254:255.255.255.0:core0.example.com:bond0:none
 ----
+
+|===
+
+[discrete]
+== `core.inst` boot options for ISO or PXE install
+
+While you can pass most standard installation boot arguments to the live installer, there are several arguments that are specific to the {op-system} live installer.
+
+* For ISO, these options can be added by interrupting the {op-system} installer.
+
+* For PXE or iPXE, these options must be added to the `APPEND` line before starting the PXE kernel. You cannot interrupt a live PXE install.
+
+The following table shows the {op-system} live installer boot options for ISO and PXE installs.
+
+.`core.inst` boot options
+[source,adoc]
+|===
+|Argument |Description
+
+a|`coreos.inst.install_dev`
+
+a|Required. The block device on the system to install to. It is recommended to use the full path, such as `/dev/sda`.
+
+a|`coreos.inst.image_url`
+
+a|Optional: Download and install the specified {op-system} image, overriding `coreos.inst.stream`.
+
+* This argument should not be used in production environments and is intended for debugging purposes only.
+
+* You must use this option if you were already using the previous `coreos-installer`.
+
+* While this argument can be used to install a version of {op-system} that does not match the live media, it is recommended that you instead use the image that matches the version you want to install.
+
+* If you are using `coreos.inst.image_url`, you must also use `coreos.inst.insecure`. This is because the bare-metal media are not GPG-signed for {product-title}.
+
+a|`coreos.inst.ignition_url`
+
+a|Optional: The URL of the Ignition config. If no URL is specified, no Ignition config will be embedded.
+
+a|`coreos.inst.platform_id`
+
+a| Optional: The Ignition platform ID of the platform the {op-system} image is being installed on. Default is bare metal. This option determines whether or not to request an Ignition config from the cloud provider, such as AWS or WMware. For example: `coreos.inst.platform_id=vmware`.
+
+a|`coreos.inst.save_partlabel`
+
+a|Optional: Comma-separated labels of partitions to preserve during the install. Glob-style wildcards are permitted. The specified partitions do not need to exist.
+
+a|`coreos.inst.save_partindex`
+
+a|Optional: Comma-separated indexes of partitions to preserve during the install. Ranges `m`-`n` are permitted, and either `m` or `n` can be omitted. The specified partitions do not need to exist.
+
+a|`coreos.inst.insecure`
+
+a|Optional: Permits the OS image to be unsigned, and installs without doing a `gpgcheck`. Must be used with `coreos.inst.image_url`.
+
+a|`coreos.inst.skip_reboot`
+
+a|Optional: The system will not reboot after installing. Once the install finishes, you will receive a prompt that allows you to inspect what is happening during installation. This argument should not be used in production environments and is intended for debugging purposes only.
+
+a|`ignition.config.url`
+
+a|Identifies the location of an Ignition config that you build to pass selected values to be used by the live installer. This argument can be used for adding disk partitioning or other features you want to have in place before the actual installation runs.
+
+|===
+
+[discrete]
+== `coreos-installer` options for ISO install
+
+You can run the `coreos-installer` command to identify various artifacts to include, to work with disk partitions, and to set up networking. In some cases, you can configure features on the live system and copy them to the installed system.
+
+This allows you to prepare the permanent system in a variety of ways before first boot.
+
+The following table shows the options and subcommands you can pass to the `coreos-installer` command from a shell prompt during a live install.
+
+.`coreos-installer` command-line options, arguments, and subcommands
+[source,adoc]
+|===
+
+2+|_Command-line options_
+
+|*Option* |*Description*
+
+a| `-u`, `--image-url <url>`
+a|Specify the image URL manually.
+
+a| `-f`, `--image-file <path>`
+a|Specify a local image file manually.
+
+a|`-i,` `--ignition-file <path>`
+a|Embed an Ignition config from a file.
+
+a|`I`, `--ignition-url <URL>`
+a|Embed an Ignition config from a URL.
+
+a|`--ignition-hash <digest>`
+a|Digest `type-value` of the Ignition config.
+
+a|`-p`, `--platform <name>`
+a|Override the Ignition platform ID.
+
+a|`--append-karg <arg>...`
+a|Append the default kernel argument.
+
+a|`--delete-karg <arg>...`
+a|Delete the default kernel argument.
+
+a|`-n`, `--copy-network`
+a|Copy the network configuration from the install environment.
+
+a|`--network-dir <path>`
+a|For use with `-n`. Default is `/etc/NetworkManager/system-connections/`.
+
+a|`--save-partlabel <lx>..`
+a|Save partitions with this label glob.
+
+a|`--save-partindex <id>...`
+a|Save partitions with this number or range.
+
+a|`--offline`
+a|Force offline installation.
+
+a|`--insecure`
+a|Skip signature verification.
+
+a|`--insecure-ignition`
+a|Allow Ignition URL without HTTPS or hash.
+
+a|`--architecture <name>`
+a|Target CPU architecture. Default is `x86_64`.
+
+a|`--preserve-on-error`
+a|Do not clear partition table on error.
+
+a|`-h`, `--help`
+a|Print help information.
+
+2+|_Command-line argument_
+
+|*Argument* |*Description*
+
+a|`<device>`
+a|The destination device.
+
+2+|_coreos-installer embedded Ignition commands_
+
+|*Command* |*Description*
+
+a|`$ coreos-installer iso ignition embed <options> <ISO_image> <Ignition_config>`
+a|Embed an Ignition config in an ISO image.
+
+a|`coreos-installer iso ignition show <options> <ISO_image> <Ignition_config>`
+|Show the embedded Ignition config from an ISO image.
+
+a|`coreos-installer iso ignition remove <options> <ISO_image> <Ignition_config>`
+a|Remove the embedded Ignition config from an ISO image.
+
+2+|_coreos-installer ISO Ignition options_
+
+|*Option* |*Description*
+
+a|`-f`, `--force`
+a|Overwrite an existing Ignition config.
+
+a|`-i`, `--ignition-file <path>`
+a|The Ignition config to be used. Default is `stdin`.
+
+a|`-o`, `--output <path>`
+a|Write the ISO to a new output file.
+
+a|`-h`, `--help`
+a|Print help information.
+
+2+|_coreos-installer PXE Ignition commands_
+
+|*Command* |*Description*
+
+a|`coreos-installer pxe ignition wrap <options> <initrd_name>`
+a|Wrap an Ignition config in an `initrd` image.
+
+a|`coreos-installer pxe ignition unwrap <options> <initrd_name>`
+a|Show the wrapped Ignition config in an `initrd` image.
+
+2+|_coreos-installer PXE Ignition options_
+
+|*Option* |*Description*
+
+a|`-i`, `--ignition-file <path>`
+a|The Ignition config to be used. Default is `stdin`.
+
+a|`-o,` `--output <path>`
+a|Write the ISO to a new output file.
+
+a|`-h`, `--help`
+a|Print help information.
+
 |===