nstnetcfg

Name

nstnetcfg — A command line network interface configuration tool for an NST system.

Synopsis

nstnetcfg [ -m TEXT | --mode TEXT ] [ -i DEVICE | --interface DEVICE ] [ -a IPv4ADDR/PREFIX | --ipv4-addr-prefix IPv4ADDR/PREFIX ] [ -a6 IPv6ADDR/PREFIX | --ipv6-addr-prefix IPv6ADDR/PREFIX ] [ -g IPv4ADDR | --gateway IPv4ADDR ] [ --mac-addr MACADDR ] [ --host-name TEXT ] [ --domain-name TEXT ] [ --name-servers IPv4ADDRLIST ] [ --hosts-file-only [true]|false ] [ --no-ipv6 [true]|false ] [ --secondary TEXT ] [ --ipv6-op TEXT ] [ --virtual-host TEXT ] [ --server-name TEXT ] [ -r DEVICE | --rename DEVICE ] [ --connection-name TEXT ] [ --modcon TEXT ] [ --promisc TEXT ] [ --bonding-slave-ints DEVICELIST ] [ --bonding-opts TEXT ] [ -h [true]|false | --help [true]|false ] [ -H [true]|false | --help-long [true]|false ] [ -v [true]|false | --verbose [true]|false ] [ --version [true]|false ]

Description

The nstnetcfg script is used in an NST distribution to assist the System Administrator with the configuration of each network interface adapter and access to the NST WUI. When an NST system is configured with two or more network interfaces, it may be easier to manage the network configuration for each interface device using this script. The nstnetcfg script's mode: "--mode ipv4" is used for setting up a static IPv4 Address on a designated network interface that can be managed by the "Network Manager" service and configured using the nmcli utility. One can also setup an IPv4 secondary Address with the "--mode secondary" mode. Currently nstnetcfg only supports "Ethernet" and "Bond" connection types.

This script is typically used with an NST system that has numerous network interfaces for providing network surveillance with hardwired attachments to Ethernet Switches, Network TAPs, SPAN Ports or Routers. It can also be used within a Virtual Machine (VM) that is Network Bridged attached.

The nstnetcfg script currently does not support the configuration of a "Wi-Fi" interface. No attempt will be done to alter this interface type. One will need to use the "Network Manager" GUI or the command line utility: "nmcli" to configure a "Wi-Fi" network interface adapter.

The nstnetcfg script can also be used to create specialized Network Interface features including: IPv4 secondary Addressing, IPv6 Addressing, Device Renaming, and Network Interface Device Bonding. IPv4 secondary Address allows you to bind multiple IPv4 Addresses onto a physical Network Interface device. Device renaming allows the ability to Rename a Network Interface Device thus providing a predictable Network Interface Name that is stable and available after each successive system reboot. Network bonding provides a method for aggregating multiple Network Interfaces into a single logical "Bonded" interface.

The Promiscuous state of a Network Interface device can be also controlled by the nstnetcfg script. One can also use the systemd service: "promisc.service" for setting the Promiscuous state 'On' for one or more Network Interface devices at system boot. One may not be able to set the Promiscuous state 'Off' if another network application like wireshark or tcpdump is active and in capture mode. A counter is used by each Kernel network driver module and incremented for each application that requests the Promiscuous mode to be set 'On' for the Network Interface device. Until these applications have all set the Promiscuous state 'Off', can one control the device's Promiscuous mode with the nstnetcfg script.

Prior to using this script, it is best to allocate or obtain a static IPv4 Address from your Domain Name Server to be used for this NST system. In a network environment that offers DHCP IPv4 Addresses, be careful not to choose an address within the configured IPv4 Address range that will be used for dynamic assignment.

***Note 1: This command should only be run on a Serial Console or a Desktop Terminal when using modes: "ipv4", "rmint" or "init" due to the fact that the IPv4 Address for this NST system will most likely change.

***Note 2: First it is best practice to 'rename' your Network Interface devices using mode: "--mode rename". This allows one to use practical device names for your environment. A system reboot will be required for any device name changes to take effect.

***Note 3: Next it is best to use the nstnetcfg initialization mode: "--mode init" prior to using any other IPv4 Address configuration nstnetcfg modes. This will establish a known network configuration state for your NST system. Afterwards, it is suggested to use the remove interface mode: "--mode rmint" before any modes that involve changing IPv4 or IPv6 Addressing.

***Note 4: One can use the macchanger utility for viewing/manipulating the MAC address for network interfaces.

See the NST Wiki page: HowTo Setup A Server With Multiple Network Interface Adapters Using: "nstnetcfg" for nstnetcfg usage examples.

Supported Modes

ipv4: If you specify 'ipv4' the static IPv4 Address: "--ipv4-addr IPv4 Address" will be bound to Interface: "--interface DEVICE". The NST system will also be configured for static IPv4 Address usage and managed by the "NetworkManager" service. Unless the option "--no-ipv6" is specified, IPv6 Addressing be will enabled and auto-assigned.

dhcp: If you specify 'dhcp' the specified Network Interface: "--interface DEVICE" will use DHCP for deriving its IPv4 Address using the "dhclient" utility and controlled by the "NetworkManager" service. Unless the option "--no-ipv6" is specified, IPv6 Addressing will be enabled and auto-assigned.

secondary: If you specify 'secondary' the static IPv4 Address: "--ipv4-addr IPv4 Address" will be added (bound) or deleted (unbound) from Interface: "--interface DEVICE". This mode allows one to bind multiple IPv4 Addresses to a Network Interface. It also requires that a Network Interface device be specified with option: "--interface DEVICE" and the option "--secondary TEXT" for adding or removing the secondary address.

ipv6: If you specify 'ipv6' the static IPv6 Address: "-a6 | --ipv6-addr IPv6 Address" will be added (bound) or deleted (unbound) from Interface: "--interface DEVICE" with global scope. This mode allows one to bind multiple IPv6 Addresses to a Network Interface. It also requires that a Network Interface device be specified with option: "--interface DEVICE" and the option "--ipv4-op TEXT" for adding or removing the IPv6 Address.

ssl: If you specify 'ssl' the static IPv4 Address bound on Interface: "--interface DEVICE" will be used in the Apache SSL configuration file: "/etc/nst/httpd/conf.d/ssl.conf" for HTTPS access and for the generation of a new SSL certificate and key file.

stealth: If you specify 'stealth' then one can configure a Network Interface device in the "UP" state with a non-binding IPv4 and IPv6 Address. This configuration can be advantageous when one wants to capturing packets in a covert or stealth manner. At system boot time this stealth network configuration will be in effect. A Network Interface put in 'stealth' mode will be 'unmanaged' by the "NetworkManager" service. The Network Interface device will be added to the "/etc/NetworkManager/conf.d/99-unmanaged-devices.conf" file as a permanent 'unmanaged' device configuration to survive a system reboot.

rmint: If you specify 'rmint' then all associated configuration entries and files for Network Interface: "--interface DEVICE" will be removed. The network interface will be put in the 'disconnected' state by "NetworkManager". You can reinitialize the 'Loopback (lo)' Network Interface with this mode. IPv6 Addressing will also be removed and disabled. A Network Interface device can be removed from the 'unmanaged' device file: "/etc/NetworkManager/conf.d/99-unmanaged-devices.conf" using this mode. The device will also be added to a 'No Auto Default' file: "/etc/NetworkManager/conf.d/98-no-auto-default.conf" so "NetworkManager" will not create a default wired connection on startup.

init: If you specify 'init' then the "NetworkManager" and the "ModemManager" will be restarted. All Network Interface devices with be put in a disconnected state with IPv6 Addressing removed and disabled. The 'LoopBack (lo)' Network Interface will be reinitialize with this mode. The 'hosts' entry in the Name Service Switch configuration file: "/etc/nsswitch.conf" will include at least the 'dns' query source parameter. All physical Network Interface devices will be added to a 'No Auto Default' file: "/etc/NetworkManager/conf.d/98-no-auto-default.conf" so "NetworkManager" will not create a default wired connection on startup.

show: If you specify 'show' then all connection information and configuration files will be displayed along with the status of network services. Use the "--connection-name TEXT" option for displaying information for that connection only otherwise all connections will be shown.

rename: If you specify 'rename' then an individual Network Interface device can be Renamed thus providing a predictable Network Interface name that is stable and available after each successive system reboot.

nmrestart: If you specify 'nmrestart' then the Network Manager Service will be restarted. Be careful of doing this action on a remote connection. The connection may be Dropped.

modcon: If you specify 'modcon' then you can modify a Network Manager Connection Profile ("--connection-name TEXT") setting. Use the "--modcon TEXT" option to specifiy the setting that will be modified. Depending on the setting modification type, a restart of the Network Manager Service "--mode nmrestart" may be required.

testudev: If you specify 'testudev' then the associated udev network rules files for the selected Network Interface: "--interface DEVICE" will be verified and displayed using the udevadm utility.

promiscon: If you specify 'promiscon' with a specific Network Interface: "--interface DEVICE" then the 'Promiscuous' state will be set 'On' for this device. If you specify 'promiscon' without a Network Interface specified then all Network Interface devices configured to set their 'Promiscuous' state with mode: "--mode promisccfg" will be set 'On'. One can use the systemd service: "promisc.service" for setting the Promiscuous state 'On' for one or more Network Interface devices at system boot.

promiscoff: If you specify 'promiscoff' with a specific Network Interface: "--interface DEVICE" then the 'Promiscuous' state will be set 'Off' for this device. If you specify 'promiscoff' without a Network Interface specified then all Network Interface devices configured to set their 'Promiscuous' state with mode: "--mode promisccfg" will be set 'Off'.

promisccfg: If you specify 'promisccfg' then a Network Interface device can be configured for controlling its 'Promiscuous' state with modes: "--mode promiscon" or "--mode promiscoff". This mode requires that a Network Interface device be specified with option: "--interface DEVICE" and the option "--promisc TEXT" for adding or removing the device.

bonding: If you specify 'bonding' then multiple Network Interface members: "--bonding-slave-ints DEVICELIST" can be aggregated into a single logical "Bonded" Interface: "--interface DEVICE" using the Linux Bonding driver.

rmbonding: If you specify 'rmbonding' then all associated configuration entries and files for Bonding Master Interface: "--interface DEVICE" and all configured Bonding Slave NIC adapter members will be removed. If this is the last Bonding Interface device, then the Linux Bonding driver module will also be unloaded.

Options

The following command line options are available:

[-m TEXT] | [--mode TEXT]: This option specifies an operational nstnetcfg mode. Currently the following modes: 'ipv4', 'dhcp', 'secondary', 'ipv6', 'ssl', 'stealth', 'rmint', 'init', 'show', 'rename', 'nmrestart', 'modcon', 'testudev', 'promiscon', 'promiscoff', 'promisccfg', 'bonding' and 'rmbonding' are supported. The description for each supported mode is described above.
[-i DEVICE] | [--interface DEVICE]: When used with mode: 'ipv4', this option will bind the static IPv4 Address: "--ipv4-addr IPv4ADDR/PREFIX" to this specific Network Interface device. When used with mode: 'ssl', this option allows one to specify a specific Network Interface device for obtaining the IPv4 Address. If not specified, the IPv4 Address for the default Network Interface will be used. Setting up an IPv4 secondary IPv4 Address can also use this mode. When used with modes: "--mode bonding" or "--mode rmbonding" this option will specify the name of the Bonding device. It is best practice to use bonding Network Interface names like: "bond0" and "bond1". Example 1: "--interface p4p1". Example 2: "--interface eno1:0". Example 3: "--interface bond0".
[-a IPv4ADDR/PREFIX] | [--ipv4-addr-prefix IPv4ADDR/PREFIX]: This option allows one to specify the static IPv4 Address to be bound to Network Interface device: "--interface DEVICE" when using modes: "--mode ipv4" and "--mode secondary". Add the 'Network Routing Prefix' to the IPv4 Address to form this option in CIDR (Classless Inter-Domain Routing) notation. Example: "--ipv4-addr-prefix 172.32.44.6/24".
[-a6 IPv6ADDR/PREFIX] | [--ipv6-addr-prefix IPv6ADDR/PREFIX]: This option allows one to specify the static IPv6 Address to be bound to Network Interface device: "--interface DEVICE" when using mode: "--mode ipv6". Add the 'Network Routing Prefix' to the IPv6 Address to form this option in CIDR (Classless Inter-Domain Routing) notation. Example: "--ipv6-addr-prefix 2001:dbc7::/32".
[-g IPv4ADDR] | [--gateway IPv4ADDR]: This option allows one to specify an IPv4 Address for the Gateway (i.e., Default Route) when setting up a static IPv4 Address on this NST system using mode: "--mode ipv4". In network computing the Gateway is the packet forwarding rule (route) that is used when no other route can be determeined for a given IPv4 Destination Address. Example: "--gateway 172.32.44.1".
[--mac-addr MACADDR]: This option allows one to override the MAC Address (Hardware Address) for a given Network Interface device: "--interface DEVICE" Route) when setting up a static IPv4 Address on this NST system using mode: "--mode ipv4". If this option is not specified, then the current associated MAC Address for the selected Network Interface device will be used. Specify the MAC Address using this format: "xx:xx:xx:xx:xx:xx". Example: "--mac-addr 40:85:A9:45:7E:37".
[--host-name TEXT]: This option allows one to specify a "Host Name" that will be associated with the static IPv4 Address when using mode: "--mode ipv4". It will be used to populate both the Hosts file: "/etc/hosts" and the Host Name file: "/etc/hostname". Use the special host name: "DNS" for automatic lookup (i.e. FQDN - A Fully Qualified Domain Name lookup) of both the "Host Name" as well as the "Domain Name". The "--domain-name" option does not need to be specified if the special case "--host-name DNS" option is used. If this parameter is used with mode: "--mode dhcp", then the "--host-name HOSTNAME" value will be used to send the "host-name" option to the DHCP server which specifies the name of the NST client system. Example: "--host-name striker".
[--domain-name TEXT]: This option allows one to specify a "Domain Name" that will be associated with the static IPv4 Address and Host Name when using mode: "--mode ipv4". It will be used to populate both the Hosts file: "/etc/hosts" and the Resolver configuration file: "/etc/resolv.conf". The "--host-name TEXT" option must be used with this option. The "--domain-name" option does not need to be specified if the special case "--host-name DNS" option is used. Example: "--domain-name balloon.org".
[--name-servers IPv4ADDRLIST]: This option allows one to specify one or more "Domain Name Servers" to be populated in the Resolver configuration file: "/etc/resolv.conf" when using mode: "--mode ipv4". Use an IPv4 Address to specify each "Domain Name Servers". Separate each IPv4 Address with a comma (,). The "--domain-name TEXT" option must be used with this option. Example: "--name-servers 172.32.44.10,172.32.44.11".
[--hosts-file-only [true]|false]: If this option is used then the nstnetcfg script will only add an updated entry to the Hosts file: "/etc/hosts". Neither the Host Name file: "/etc/hostname" nor the Resolver configuration file: "/etc/resolv.conf" will be altered. This option is typically used for multi-homed (i.e., A system with two or more active Network Interfaces.) network configurations.
[--no-ipv6 [true]|false]: If this option is used then IPv6 Addressing will be disabled for the selected interface. This option is typically used with modes: "--mode ipv4" and "--mode dhcp". The following will be done when disabling IPv6 Addressing: 1) If the Network Interface has an existing IPv6 Address it will be disabled and removed using the sysctl command. 2) An entry to permanently disable IPv6 Addressing for the Network Interface will be made in file: "/etc/sysctl.conf".
[--secondary TEXT]: Use this option with mode "--mode secondary" to add (bind) or remove (unbind) an IPv4 secondary Address to Network Interface device: "--interface DEVICE". Specify "add" (default) to bind the IPv4 secondary Address or "remove" to unbind the address.
[--ipv6-op TEXT]: Use this option with mode "--mode ipv6" to add (bind) or remove (unbind) an IPv6 Address to Network Interface device: "--interface DEVICE". Specify "add" (default) to bind the IPv6 Address or "remove" to unbind the address.
[--virtual-host TEXT]: This option may be used in conjunction with mode "--mode ssl" to set the Apache "VirtualHost" directive in the SSL configuration file: "/etc/nst/httpd/conf.d/ssl.conf" for the NST WUI. The syntax for using this option is: "IPAddr:Port IPAddr:Port ...". The IPv4 Address of the NST system may be used. The "Port" value is ususally set to match the Apache SSL listening directive: "Listen" for standard HTTPS access (i.e., 9943). Separate two or more "IPAddr:Port" combination values with a space. Use double quotes when specifying this option. If this value is not specified, then the default value: "*:9943" will be used. Example: '--virtual-host "172.32.44.6:9943"'.
[--server-name TEXT]: This option may be used in conjunction with mode "--mode ssl" to set the Apache "ServerName" directive in the SSL configuration file: "/etc/nst/httpd/conf.d/ssl.conf". The syntax for using this option is: "IPAddr:Port or Fully-Qualified-Domain-Name:Port". The "Port" value is ususally set to match the Apache SSL listening directive: "Listen" for standard HTTPS access (i.e., 9943 for the NST WUI). The IPv4 Address or Host Name of the NST system should be used. If this value is not specified, then the default IPv4 Address of the NST system will be used. Example 1: "--server-name 172.32.44.6:9943". Example 2: "--server-name nst.securenet.compxyz.com:9943"
[-r DEVICE] | [--rename DEVICE]: This option must be used with mode: 'rename'to configure the udev network rules file: "/etc/udev/rules.d/79-my-net-name-slot.rules" for renaming the specified Network Interface device: "--interface DEVICE" to the Network Interface name: "--rename DEVICE". The MAC Address (Hardware Address) will be used to identify the Network Interface device: "--interface DEVICE". One can override the native MAC Address using the "--mac-addr MACADDR" option. Typically, one needs to 'Reboot' the system for this device name change to take effect. The "NetworkManager" or the "network" configuration file for this Network Interface will also be renamed. Note: The device name can only consist of alphanumeric or underscore characters with the first character alphabetical only. Example: "--rename fw0"
[--connection-name TEXT]: This option may be used in conjunction with mode "--mode show" to display Network Manager connection information for this "Connection ID (Name)" only. Enclose a connection name option value in outer double quotes with single quotes around the name if it contains a space (e.g. --connection-name "'Wired connection 1'").
[--modcon TEXT]: This option must be used with mode: '--mode modcon' to modify a connection setting. Example 1: --connection-name "'Wired connection 1'" --modcon "ipv4.route-metric 99". This sets the IPv4 route metric to "99" for Network Manager connection name: "Wired connection 1". Example 2: --connection-name lan0 --modcon "connection.id 'net0 lan0'". Enclose a connection setting option value in outer double quotes with single quotes around the modification if it contains a space. This example changes the connection ID (name) from "lan0" to "net0 lan0".
[--promisc TEXT]: Use this option with mode "--mode promisccfg" to add or remove the specified Network Interface device: "--interface DEVICE" to configuration file: "/etc/nst/promisc.conf" for controlling the device's Promiscuous state with modes: "--mode promiscon" or "--mode promiscoff". Specify "add" (default) to add the device or "remove" to delete it from this file.
[--bonding-slave-ints DEVICELIST]: Specify a list of Network Interface Slave Bonding devices that will be used as member NIC adapters when configuring a Bonding Interface: "--mode bonding". Separate each specified Network Interface with a comma (,). Example: "--bonding-slave-ints p2p1,p2p2"
[--bonding-opts TEXT]: Use this parameter to specify one or more options to the Linux Bonding driver module. Enclose this parameter within single (') or double quotes (") and separate each option with a space delimiter. By default, the bonding policy: "Round-Robin (mode=balance-rr)" and the MII link monitoring frequency in milliseconds: 'miimon=100' will be used. See the document: "/usr/share/doc/kernel-doc-[Kernel Version]/Documentation/networking/bonding.txt" for detailed option information. Example: "--bonding-opts 'mode=balance-rr,miimon=400,updelay=800'"
[-h [true]|false] | [--help [true]|false]: When this option is specified, nstnetcfg will display a short one line description of nstnetcfg, followed by a short description of each of the supported command line options. After displaying this information nstnetcfg will terminate.
[-H [true]|false] | [--help-long [true]|false]: This option will attempt to pull up additional nstnetcfg documentation within a text based web browser. You can force which browser we use setting the environment variable TEXTBROWSER, otherwise, we will search for some common ones.
[-v [true]|false] | [--verbose [true]|false]: When you set this option to true, nstnetcfg will produce additional output. This is typically used for diagnostic purposes to help track down when things go wrong.
[--version [true]|false]: If this option is specified, the version number of the script is displayed.

Files

/etc/hostname: Configuration file for setting the system host name.
/etc/hosts: Static table lookup file for host names.
/etc/nst/promisc.conf: List of Network Interface adapters configured by nstnetcfg - mode: "promisccfg" for Promiscuous mode control.
/etc/resolv.conf: Domain name resolver configuration file.
/etc/udev/rules.d/79-my-net-name-slot.rules: Custom udev network rules policy file.
/usr/lib/udev/rules.d/80-net-name-slot.rules: Default udev network rules policy file.
/etc/sysconfig/network: Global network configuration file.
/etc/sysctl.conf: Global sysctl configuration file.
/etc/NetworkManager/system-connections: Directory containing the settings for all Network Connections.
/etc/NetworkManager/conf.d/98-no-auto-default.conf: File containing devices that NetworkManager will not create a default wired connection for.
/etc/NetworkManager/conf.d/99-unmanaged-devices.conf: File containing devices that NetworkManager will ignore (unmanaged).
/usr/lib/systemd/system/promisc.service: A Systemd service unit configuration: "promisc.service" - Used to control the Promiscuous mode of one or more Network Interface adapters defined in file: "/etc/nst/promisc.conf" during system boot. Internally uses nstnetcfg - mode: "promiscon".

Environment

TEXTBROWSER: This controls what text based browser is used to display help information about the script. If not set, we will search your system for available text-based browsers (Ex: elinks, lynx ...).