netwrangler

README

NetWrangler

Table of Contents

• Introduction
• Using NetWrangler
• Building NetWrangler
• Cross Compiling
• Contributing
• Input Configuration File Format
• License

Introduction

NetWrangler is a one-shot network interface configuration utility that is mostly compatible with https://netplan.io configuration files. Key differences are:

• It only supports systemd-networkd and old-style Redhat network configurations as output formats. Debian style is a planned on, and NetworkManager style is a lower priority.
• No support for configuring wireless interfaces. This tool is mainly intended for servers and other devices that do not have wireless interfaces.
• No daemons, dynamic configuration, or other long-lived operations. This tool is intended to be run as part of device provisioning, where we expect to set the desired network interface config once and then forget about it until it is time to reprovision the box.
• No support for hierarchical config files. We use the netplan.io YAML for its schema, not to allow additional layered customization.
• No support for NIC renaming or MAC address reassignment. Support may be added at a later date.
• Where the netplan.io spec calls for glob expansion, we also allow full regular expressions, as long as the match in question starts with ^.
• No support for per-interface backend renderers. This just doesn't seem like a good idea if you don't care about dynamic interface reconfiguration.
• Support for a few interesting generic interface match names in the netplan:
  • bootif is the interface the system last booted from. You need to set the -bootmac flag to the MAC address of the interface for this name to be recognized.
  • onboard:1 ... onboard:n The first through nth onboard nics. Whether a nic is onboard or not is determined by what udev thinks.
  • pci:1 ... pci:n The first through nth nic in PCI expansion slots. These nics are always ordered by their PCI bus ordering, which can vary on a system by system basis.
  • usb:1 ... usb:n The first through nth USB nics, also ordered by bus order. If you want to use one of these, make sure it stays plugged in to the same USB port.

Using NetWrangler

There are extensive example configuration files for various network configuration implementations which can be found in the test-data directory.

For basic command usage, use the --help switch to the compiled binary for more details. Example usage (not guaranteed to be up to date with current usage output):

$ netwrangler --help
Usage of cmd/netwrangler:
  -bindMacs
    	Whether to write configs that force matching physical devices on MAC address
  -bootmac string
    	Mac address of the nic the system booted from.  Required for magic bootif name matching
  -dest string
    	Location to write output to.  Defaults to stdout.
  -in string
    	Format to expect for input. Options: netplan, internal (default "netplan")
  -op string
    	Operation to perform.
    	"gather" gathers information about the physical nics on the system in a form that can be used later with the -phys option
    	"compile" translates the -in formatted network spec from -src to -out formatted data at -dest
  -out string
    	Format to render input to.  Options: systemd, rhel, internal (default "systemd")
  -phys string
    	File to read to gather current physical nics.  Defaults to reading them from the kernel.
  -src string
    	Location to get input from.  Defaults to stdin.
2019/06/25 16:16:40 flag: help requested

Building NetWrangler

NetWrangler is a Go Lang project, and is simple to build. Please install Go version 1.12 or newer (older versions may work but have not been tested). See [https://golang.org/doc/install[(https://golang.org/doc/install)

In the future, compiled builds may be provided.

These examples work on Linux or Mac. You may need to adjust directories appropriately for your Go environment. Check out the source code:

go get github.com/rackn/netwrangler

This will checkout the code and (generally) put it in:

$HOME/go/src/github.com/rackn/netwrangler

To build it, change to the netwrangler directory and run the build script, and copy the binary to your path or remote system:

cd $HOME/go/src/github.com/rackn/netwrangler
tools/build.sh
cp cmd/netwrangler /usr/local/bin

Cross Compiling

Standard Go Lang cross compiling methodology works here, see: https://golang.org/doc/install/source#environment

Example of compiling for Linux 64bit, when on macOS:

env GOOS=linux GOARCH=amd64 tools/build.sh

Contributing

We encourage contributions to help expand and enhance the functionality of the NetWrangler project. We operate in a standard "Pull Request" (PR) git workflow model.

We also require that contributors sign a Contributor's License Agreement. We believe that this helps protect both you the contributor, and the project at large. You can find our philosophy on this summarized by the excellent post by Julian Ponge. For reference, we have copied this post to a GIST backup.

You may sign the CLA in advance of submitting changes by visiting:

• https://cla-assistant.io/rackn/netwrangler

When you create your first Pull Request, you will be required to sign the CLA if you have not yet done so.

If you have some changes you'd like to make, we ask that you drop by and chat with us via Slack, sign up at:

• https://rackn.com/support/slack/

Please put "netwrangler" in the "I'm interested in" field.

We will add you to the NetWrangler Members for write access to the repository.

For small fixes and enhancements, please go ahead and submit a PR, with sufficient comments for us to understand what your intentions are.

If you would like to add a new configuration method (for example, add full NetworkManager) support, please drop us a note and let us know, we'd appreciate it.

Input Configuration File Format

The configuration input is via the netplan.io DSL. Please refer to it for full details.

License

NetWrangler is Apache License 2.0.

To contribute to the Netwrangler repo, please fork and submit a PUll Request on a Branch. You will need to sign the Digital Rebar Community License Agreement prior to submitting the PR. Thank you in advance for your contributions!

Documentation

Index

• Variables
• func BootMac(mac string) error
• func Compile(phys []util.Phy, srcFmt, destFmt, srcLoc, destLoc string, bindMacs bool) error
• func GatherPhys() ([]util.Phy, error)
• func GatherPhysFromFile(src string) (phys []util.Phy, err error)
• func Write(layout *util.Layout, destFmt, destLoc string, bindMacs bool) error

Variables

var (
	// The input formats we accept.  internal is the intermediate format netwrangler uses.
	SrcFormats = []string{"netplan", "internal"}
	// The output formats we can handle.  internal is the intermediate format netwrangler uses.
	DestFormats = []string{"netplan", "systemd", "rhel", "internal"}
)

Functions

func BootMac

func BootMac(mac string) error

BootMac arranges for setting the BootIf flag on the phy corresponding to the interface we booted from. Must be called before phys are gathered.

func Compile

func Compile(phys []util.Phy, srcFmt, destFmt, srcLoc, destLoc string, bindMacs bool) error

Compile transforms network configuration settings from srcLoc in srcFmt into destFmt at destLoc, using phys as the base physical interfaces to build on. if bindMacs is true, the generated format will bind to interface MAC addresses (or other unique physical addresses), otherwise the interface names at srcLoc must match what is present on the system at the time netwrangler is run.

func GatherPhys

func GatherPhys() ([]util.Phy, error)

GatherPhys gathers the physical nics that the system knows about. It is currently only supported on Linux systems.

func GatherPhysFromFile

func GatherPhysFromFile(src string) (phys []util.Phy, err error)

GatherPhysFromFile gathers the physical nic information from a saved file. This can be used for unit testing or buld offline operations.

func Write

func Write(layout *util.Layout, destFmt, destLoc string, bindMacs bool) error

Write writes out the compiled Layout in the specified format and location