From b4d78963f94e2fe9d42df0520076a93948f44b66 Mon Sep 17 00:00:00 2001 From: Gregory Kurtzer Date: Mon, 21 Dec 2020 18:47:54 -0800 Subject: [PATCH] Starting documentation updates --- README.md | 2 +- docs/README.md | 7 ++ docs/rhel7-quickstart.md | 146 +++++++++++++++++++++++++++++++++++++++ docs/rhel8-quickstart.md | 146 +++++++++++++++++++++++++++++++++++++++ 4 files changed, 300 insertions(+), 1 deletion(-) create mode 100644 docs/README.md create mode 100644 docs/rhel7-quickstart.md create mode 100644 docs/rhel8-quickstart.md diff --git a/README.md b/README.md index c9d011b3..e00899ab 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -# warewulf v4 (work in progress) +# warewulf v4 ![Warewulf](warewulf-logo.png) diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 00000000..7226386a --- /dev/null +++ b/docs/README.md @@ -0,0 +1,7 @@ +# Documentation for Warewulf + +### Quickstarts + +* [RHEL-7 quickstart](rhel7-quickstart.md) +* [RHEL-8 quickstart](rhel8-quickstart.md) + diff --git a/docs/rhel7-quickstart.md b/docs/rhel7-quickstart.md new file mode 100644 index 00000000..37288c9b --- /dev/null +++ b/docs/rhel7-quickstart.md @@ -0,0 +1,146 @@ +## Quick Start for RHEL, CentOS, and Rocky Linux version 7 + +#### Install Warewulf and dependencies +``` +sudo yum install epel-release +sudo yum install --tolerant golang tftp-server dhcp dhcp-server + +sudo systemctl stop firewalld +sudo systemctl disable firewalld + +git clone https://github.com/ctrliq/warewulf.git +cd warewulf +make all +sudo make install +``` + +#### Configure the controller: + +Edit the file `/etc/warewulf/warewulf.conf` and ensure that you've set the +appropriate configuration paramaters. Here are some of the defaults for reference: + +``` +ipaddr: 192.168.1.1 +netmask: 255.255.255.0 +warewulf: + port: 9873 + secure: true + update interval: 60 +dhcp: + enabled: true + range start: 192.168.1.150 + range end: 192.168.1.200 + template: default + systemd name: dhcpd +tftp: + enabled: true + tftproot: /var/lib/tftpboot + systemd name: tftp +nfs: + systemd name: nfs-server + exports: + - /home + - /var/warewulf +``` + +#### Configure system services automatically + +``` +sudo ./wwctl configure dhcp # Create the default dhcpd.conf file and start/enable service +sudo ./wwctl configure tftp # Install the base tftp/PXE boot files and start/enable service +sudo ./wwctl configure nfs # Configure the exports and create an fstab in the default system overlay +sudo ./wwctl configure ssh # Build the basic ssh keys to be included by the default system overlay +``` + + +#### Pull and build the VNFS container and kernel: +This will pull a basic VNFS container from Docker Hub and import the default running +kernel from the controller node and set both in the "default" node profile. + +``` +sudo ./wwctl container pull docker://warewulf/centos-7 centos-7 --setdefault +sudo ./wwctl kernel build $(uname -r) --setdefault +``` + +#### Set up the default node profile + +The `--setdefault` arguments above will automatically set those entries in the default +profile, but if you wanted to set them by hand to something different, you can do the +following: + +``` +sudo ./wwctl profile set default -K $(uname -r) -C centos-7 +``` + +Next we set some default networking configurations for the first ethernet device. On +modern Linux distributions, the name of the device is not critical, as it will be setup +according to the HW address. Because all nodes will share the netmask and gateway +configuration, we can set them in the default profile as follows: + +``` +sudo ./wwctl profile set default --netdev eth0 -M 255.255.255.0 -G 192.168.1.1 +sudo ./wwctl profile list +``` + +#### Add a node and build node specific overlays + +Adding nodes can be done while setting configurations in one command. Here we are setting +the IP address of `eth0` and setting this node to be discoverable, which will then +automatically have the HW address added to the configuration as the node boots. + +Node names must be unique. If you have node groups and/or multiple clusters, designate +them using dot notation. + +Note that the full node configuration comes from both cascading profiles and node +configurations which always supersede profile configurations. + +``` +sudo ./wwctl node add n0000.cluster --netdev eth0 -I 192.168.1.100 --discoverable +sudo ./wwctl node list -a n0000 +``` + +### Warewulf Overlays + +There are two types of overlays: system and runtime overlays. + +System overlays are provisioned to the node before `/sbin/init` is called. This enables us +to prepopulate node configurations with content that is node specific like networking and +service configurations. + +Runtime overlays are provisioned after the node has booted and periodically during the +normal runtime of the node. Because these overlays are provisioned at periodic intervals, +they are very useful for content that changes, like users and groups. + +Overlays are generated from a template structure that is viewed using the `wwctl overlay` +commands. Files that end in the `.ww` suffix are templates and abide by standard +text/template rules. This supports loops, arrays, variables, and functions making overlays +extremely flexible. + +*note: When using the overlay subsystem, system overlays are never shown by default. So +when running `overlay` commands, you are always looking at runtime overlays unless the +`-s` option is passed.* + +All overlays are compiled before being provisioned. This accelerates the provisioning +process because there is less to do when nodes are being managed at scale. + +Here are some of the common `overlay` commands: + +``` +sudo ./wwctl overlay list -l +sudo ./wwctl overlay list -ls +sudo EDITOR=vim ./wwctl overlay edit default /etc/hello_world.ww +sudo ./wwctl overlay build -a +``` + +#### Start the Warewulf daemon: + +Once the above provisioning images are built, you can check the provisioning "rediness" +and then begin booting nodes. + +``` +sudo ./wwctl ready +sudo ./wwctl server start +sudo ./wwctl server status +``` + +#### Boot your compute node and watch it boot diff --git a/docs/rhel8-quickstart.md b/docs/rhel8-quickstart.md new file mode 100644 index 00000000..21c2ee63 --- /dev/null +++ b/docs/rhel8-quickstart.md @@ -0,0 +1,146 @@ +## Quick Start for RHEL, CentOS, and Rocky Linux version 8 + +#### Install Warewulf and dependencies +``` +sudo yum install epel-release +sudo yum install --tolerant golang tftp-server dhcp dhcp-server + +sudo systemctl stop firewalld +sudo systemctl disable firewalld + +git clone https://github.com/ctrliq/warewulf.git +cd warewulf +make all +sudo make install +``` + +#### Configure the controller: + +Edit the file `/etc/warewulf/warewulf.conf` and ensure that you've set the +appropriate configuration paramaters. Here are some of the defaults for reference: + +``` +ipaddr: 192.168.1.1 +netmask: 255.255.255.0 +warewulf: + port: 9873 + secure: true + update interval: 60 +dhcp: + enabled: true + range start: 192.168.1.150 + range end: 192.168.1.200 + template: default + systemd name: dhcpd +tftp: + enabled: true + tftproot: /var/lib/tftpboot + systemd name: tftp +nfs: + systemd name: nfs-server + exports: + - /home + - /var/warewulf +``` + +#### Configure system services automatically + +``` +sudo ./wwctl configure dhcp # Create the default dhcpd.conf file and start/enable service +sudo ./wwctl configure tftp # Install the base tftp/PXE boot files and start/enable service +sudo ./wwctl configure nfs # Configure the exports and create an fstab in the default system overlay +sudo ./wwctl configure ssh # Build the basic ssh keys to be included by the default system overlay +``` + + +#### Pull and build the VNFS container and kernel: +This will pull a basic VNFS container from Docker Hub and import the default running +kernel from the controller node and set both in the "default" node profile. + +``` +sudo ./wwctl container pull docker://warewulf/centos-7 centos-7 --setdefault +sudo ./wwctl kernel build $(uname -r) --setdefault +``` + +#### Set up the default node profile + +The `--setdefault` arguments above will automatically set those entries in the default +profile, but if you wanted to set them by hand to something different, you can do the +following: + +``` +sudo ./wwctl profile set default -K $(uname -r) -C centos-7 +``` + +Next we set some default networking configurations for the first ethernet device. On +modern Linux distributions, the name of the device is not critical, as it will be setup +according to the HW address. Because all nodes will share the netmask and gateway +configuration, we can set them in the default profile as follows: + +``` +sudo ./wwctl profile set default --netdev eth0 -M 255.255.255.0 -G 192.168.1.1 +sudo ./wwctl profile list +``` + +#### Add a node and build node specific overlays + +Adding nodes can be done while setting configurations in one command. Here we are setting +the IP address of `eth0` and setting this node to be discoverable, which will then +automatically have the HW address added to the configuration as the node boots. + +Node names must be unique. If you have node groups and/or multiple clusters, designate +them using dot notation. + +Note that the full node configuration comes from both cascading profiles and node +configurations which always supersede profile configurations. + +``` +sudo ./wwctl node add n0000.cluster --netdev eth0 -I 192.168.1.100 --discoverable +sudo ./wwctl node list -a n0000 +``` + +### Warewulf Overlays + +There are two types of overlays: system and runtime overlays. + +System overlays are provisioned to the node before `/sbin/init` is called. This enables us +to prepopulate node configurations with content that is node specific like networking and +service configurations. + +Runtime overlays are provisioned after the node has booted and periodically during the +normal runtime of the node. Because these overlays are provisioned at periodic intervals, +they are very useful for content that changes, like users and groups. + +Overlays are generated from a template structure that is viewed using the `wwctl overlay` +commands. Files that end in the `.ww` suffix are templates and abide by standard +text/template rules. This supports loops, arrays, variables, and functions making overlays +extremely flexible. + +*note: When using the overlay subsystem, system overlays are never shown by default. So +when running `overlay` commands, you are always looking at runtime overlays unless the +`-s` option is passed.* + +All overlays are compiled before being provisioned. This accelerates the provisioning +process because there is less to do when nodes are being managed at scale. + +Here are some of the common `overlay` commands: + +``` +sudo ./wwctl overlay list -l +sudo ./wwctl overlay list -ls +sudo EDITOR=vim ./wwctl overlay edit default /etc/hello_world.ww +sudo ./wwctl overlay build -a +``` + +#### Start the Warewulf daemon: + +Once the above provisioning images are built, you can check the provisioning "rediness" +and then begin booting nodes. + +``` +sudo ./wwctl ready +sudo ./wwctl server start +sudo ./wwctl server status +``` + +#### Boot your compute node and watch it boot