From 79b49ccd3a7b093d5896f208c96bfd2bdb368515 Mon Sep 17 00:00:00 2001 From: Jonathon Anderson Date: Wed, 24 Aug 2022 01:14:12 -0600 Subject: [PATCH 1/7] Initial commit of new warewulf.conf manpage Signed-off-by: Jonathon Anderson --- docs/man/man5/warewulf.conf.5 | 315 ++++++++++++++++++++++++++++++++++ 1 file changed, 315 insertions(+) create mode 100644 docs/man/man5/warewulf.conf.5 diff --git a/docs/man/man5/warewulf.conf.5 b/docs/man/man5/warewulf.conf.5 new file mode 100644 index 00000000..612f63ca --- /dev/null +++ b/docs/man/man5/warewulf.conf.5 @@ -0,0 +1,315 @@ +.TH "WAREWULF.CONF" "5" + +.SH NAME + +warewulf.conf \- warewulf server configuration file + +.SH DESCRIPTION +.LP +\fBwarewulf.conf\fP is the main configuration file for the warewulf +server daemon and defines the configuration for its service +dependencies, including dhcp, tftp, and nfs. +.LP +warewulf.conf is defined using YAML document markup syntax. + +.SH PARAMETERS +.LP +The configuration parameters available include: + +.TP +\fBWW_INTERNAL\fP +Specifies the version of the configuration file format. The current +version is 43. +.IP + +.TP +\fBipaddr\fP +This is the control node's networking interface connecting to the +cluster's PRIVATE network. This configuration must match the host's +network IP address for the cluster's private interface. + +.IP + +.TP +\fBnetwork\fP +The subnet address for the cluster's PRIVATE network, used in +conjunction with the netmask parameter. +.IP + +.TP +\fBnetmask\fP +Similar to the ipaddr, this is the subnet mask for the cluster's +PRIVATE network and it must also match the host's subnet mask for the +cluster's private interface. +.IP + +.SS WAREWULF +.LP +The \fBwarewulf\fP parameter is a map of individual sub-parameters +which configure warewulf specifically. (See the \fBEXAMPLE\fP section +for overall structure.) + +.TP +\fBport\fP + +This is the port that the Warewulf web server will be listening on. It +is recommended not to change this so there is no misalignment with +node's expectations of how to contact the Warewulf service. + +Default: 9983 +.IP + +.TP +\fBsecure\fP + +When true, this limits the Warewulf server to only respond to runtime +overlay requests originating from a privileged report port. This makes +it so that only the root user on a compute node can request the +runtime overlay. While generally there is nothing super "secure" in +these overlays, this adds the necessary protection that the users can +not obtain this information. + +When true, wwclient uses TCP port 987. + +Default: true +.IP + +.TP +\fBupdate interval\fP + +The frequency (in seconds) with which wwclient will fetch its +configuration (e.g., its overlays) from the Warewulf server. + +Default: 60 +.IP + +.TP +\fBautobuild overlays\fP + +When true, overlays will be automatically rebuilt when indicated by +changes to nodes, profiles, and overlays. + +Default: true +.IP + +.TP +\fBhost overlay\fP + +Host overlays are used to configure dependent services on the Warewulf +server. When disabled, these services' configuration files will not be +updated by \fBwwctl-configure(1)\fP. + +Default: true +.IP + +.TP +\fBsyslog\fP + +When true, warewulf server logs are written to syslog, rather than a +local file. + +When false, warewulf server logs are written to +`/var/log/warewulfd.log'. + +Default: false +.IP + +.TP +\fBdatastore\fP + +The location where Warewulf caches and stores OCI data. + +Default: /var/lib/warewulf +.IP + +.SS DHCP +.LP +The \fBdhcp\fP parameter is a map of individual sub-parameters which +inform how \fBwwctl-configure(1)\fP should configure the DHCP +service. (See the \fBEXAMPLE\fP section for overall structure.) + +.TP +\fBenabled\fP + +When false, the DHCP service will not be configured by +\fBwwctl-configure(1)\fP. + +Default: true +.IP + +.TP +\fBrange start\fP + +An IP address which defines the start of a dynamic address range which +can be used when configuring the DHCP service. Provided to the host +overlay as the variable \fB$.Dhcp.RangeStart\fP, typically for use in +generating dhcpd.conf or similar. + +Templates typically expect this range to be within the \fBnetwork\fP +defined above. +.IP + +.TP +\fBrange end\fP + +An IP address which defines the end of a dynamic address range which +can be used when configuring the DHCP service. Provided to the host +overlay as the variable \fB$.Dhcp.RangeEnd\fP, typically for use in +generating dhcpd.conf or similar. + +Templates typically expect this range to be within the \fBnetwork\fP +defined above. +.IP + +.TP +\fBsystemd name\fP + +The systemd unit name which will be used to (re)start the DHCP service +during \fBwwctl-configure(1)\fP, if necessary. + +Default: dhcpd +.IP + +.SS TFTP +.LP +The \fBtftp\fP parameter is a map of individual sub-parameters which +inform how \fBwwctl-configure(1)\fP should configure the TFTP +service. (See the \fBEXAMPLE\fP section for overall structure.) + +.TP +\fBenabled\fP + +When false, the TFTP service will not be configured by +\fBwwctl-configure(1)\fP. + +Default: true +.IP + +.TP +\fBsystemd name\fP + +The systemd unit name which will be used to (re)start the TFTP service +during \fBwwctl-configure(1)\fP, if necessary. + +Default: tftp +.IP + +.SS NFS +.LP +The nfs parameter is a map of individual sub-parameters which inform +how \fBwwctl-configure(1)\fP should configure the NFS service. (See +the \fBEXAMPLE\fP section for overall structure.) + +.TP +\fBenabled\fP + +When false, the NFS service will not be configured by +\fBwwctl-configure(1)\fP. + +Default: true +.IP + +.TP +\fBexport paths\fP + +A list of paths to be exported by the NFS service and, optionally, to +be automatically mounted on compute nodes. Each item in the list is, +itself, a map of parameters for the mount. (See the \fBEXAMPLE\fP +section for overall structure.) + +.RS +.TP +\fBpath\fP + +The path on the server to be exported via the NFS service. Provided to +the host overlay as the variable \fB.Nfs.ExportsExtended[].Path\fP, +typically for use in generating /etc/exports or similar. +.IP + +.TP +\fBexport options\fP + +The NFS export options to use when exporting the given \fBpath\fP via +the NFS service. Provided to the host overlay as the variable +\fB.Nfs.ExportsExtended[].ExportOptions\fP, typically for use in +generating /etc/exports or similar. + +Default: rw,sync,no_subtree_check +.IP + +.TP +\fBmount options\fP + +The NFS mount options to use when mounting the given \fBpath\fP on +compute nodes via the NFS service. Provided to the compute node's +overlays as the variable \fB.Nfs.ExportsExtended[].MountOptions\fP, +typically for use in generating /etc/fstab or similar. + +Default: defaults +.IP + +.TP +\fBmount\fP + +If true, mount the NFS share automatically on compute nodes. Provided +to the compute node's overlays as the variable +\fB.Nfs.ExportsExtended[].Mount\fP, typically for use in generating +/etc/fstab or similar. + +Default: true +.IP +.RE +.IP + +.TP +\fBsystemd name\fP + +The systemd unit name which will be used to (re)start the NFS service +during \fBwwctl-configure(1)\fP, if necessary. + +Default: nfsd +.IP + +.SH EXAMPLE +.LP +A sample configuration file for a typical deployment, with all +dependent services enabled. + +.EX +WW_INTERNAL: 43 +ipaddr: 10.0.0.1 +network: 10.0.0.0 +netmask: 255.255.0.0 +warewulf: + port: 9873 + secure: false + update interval: 60 + autobuild overlays: true + host overlay: true + syslog: false + datastore: "" +dhcp: + enabled: true + range start: 10.0.0.10 + range end: 10.0.0.99 + systemd name: dhcpd +tftp: + enabled: true + systemd name: tftp +nfs: + enabled: true + export paths: + - path: /home + export options: rw,sync + mount options: defaults + mount: true + - path: /opt + export options: ro,sync,no_root_squash + mount options: defaults + mount: true + systemd name: nfs-server +.EE + +.SH SEE ALSO + +\fBwwctl\-server(1)\fP, \fBwwctl-configure(1)\fP, \fBnodes.conf(5)\fP From f1fddf81af8145a7c366ce5731c9dac51a2e727f Mon Sep 17 00:00:00 2001 From: Jonathon Anderson Date: Wed, 24 Aug 2022 01:20:49 -0600 Subject: [PATCH 2/7] Don't use all-caps for PRIVATE network in man Signed-off-by: Jonathon Anderson --- docs/man/man5/warewulf.conf.5 | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/man/man5/warewulf.conf.5 b/docs/man/man5/warewulf.conf.5 index 612f63ca..d134ac52 100644 --- a/docs/man/man5/warewulf.conf.5 +++ b/docs/man/man5/warewulf.conf.5 @@ -25,21 +25,21 @@ version is 43. .TP \fBipaddr\fP This is the control node's networking interface connecting to the -cluster's PRIVATE network. This configuration must match the host's +cluster's private network. This configuration must match the host's network IP address for the cluster's private interface. .IP .TP \fBnetwork\fP -The subnet address for the cluster's PRIVATE network, used in +The subnet address for the cluster's private network, used in conjunction with the netmask parameter. .IP .TP \fBnetmask\fP Similar to the ipaddr, this is the subnet mask for the cluster's -PRIVATE network and it must also match the host's subnet mask for the +private network and it must also match the host's subnet mask for the cluster's private interface. .IP From c369ff881155ed77a30395e480590fdd85f75581 Mon Sep 17 00:00:00 2001 From: Jonathon Anderson Date: Wed, 24 Aug 2022 03:08:35 -0600 Subject: [PATCH 3/7] Add ipaddr6 to warewulf.conf man Signed-off-by: Jonathon Anderson --- docs/man/man5/warewulf.conf.5 | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/docs/man/man5/warewulf.conf.5 b/docs/man/man5/warewulf.conf.5 index d134ac52..d64b28cf 100644 --- a/docs/man/man5/warewulf.conf.5 +++ b/docs/man/man5/warewulf.conf.5 @@ -27,7 +27,13 @@ version is 43. This is the control node's networking interface connecting to the cluster's private network. This configuration must match the host's network IP address for the cluster's private interface. +.IP +.TP +\fBipaddr6\fP +This is the control node's networking interface connecting to the +cluster's IPv6 private network. This configuration must match the +host's network IP address for the cluster's private interface. .IP .TP From 351d5dbf0ae682f0332e2af3b177422b1b976fc6 Mon Sep 17 00:00:00 2001 From: Jonathon Anderson Date: Wed, 24 Aug 2022 03:58:09 -0600 Subject: [PATCH 4/7] More generic defaults for warewulf.conf Signed-off-by: Jonathon Anderson --- internal/pkg/warewulfconf/datastructure.go | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/internal/pkg/warewulfconf/datastructure.go b/internal/pkg/warewulfconf/datastructure.go index 887d11ef..ef43a2ae 100644 --- a/internal/pkg/warewulfconf/datastructure.go +++ b/internal/pkg/warewulfconf/datastructure.go @@ -35,8 +35,8 @@ type WarewulfConf struct { type DhcpConf struct { Enabled bool `yaml:"enabled" default:"true"` Template string `yaml:"template" default:"default"` - RangeStart string `yaml:"range start" default:"192.168.200.50"` - RangeEnd string `yaml:"range end" default:"192.168.200.99"` + RangeStart string `yaml:"range start,omitempty"` + RangeEnd string `yaml:"range end,omitempty"` SystemdName string `yaml:"systemd name" default:"dhcpd"` } @@ -48,12 +48,12 @@ type TftpConf struct { type NfsConf struct { Enabled bool `yaml:"enabled" default:"true"` - ExportsExtended []*NfsExportConf `yaml:"export paths" default:"[{\"Path\": \"home\"}]"` + ExportsExtended []*NfsExportConf `yaml:"export paths" default:"[]"` SystemdName string `yaml:"systemd name" default:"nfsd"` } type NfsExportConf struct { - Path string `yaml:"path" default:"/home"` + Path string `yaml:"path" default:"/dev/null"` ExportOptions string `default:"rw,sync,no_subtree_check" yaml:"export options"` MountOptions string `default:"defaults" yaml:"mount options"` Mount bool `default:"true" yaml:"mount"` From 77baa76dc0e3dcb740413d0d6bd23ec1d73d51be Mon Sep 17 00:00:00 2001 From: Jonathon Anderson Date: Wed, 24 Aug 2022 04:47:56 -0600 Subject: [PATCH 5/7] Remove unnecessary config parameter examples warewulf.datastore is being set to a null string, which is simply prompting it to use the default. dhcp.template doesn't appear to be used any more, now that dhcp configuration has moved into the host overlay. tftp.tftproot doesn't appear to be doing anything, is simply setting to the empty string anyway, and is otherwise compiled-in. Signed-off-by: Jonathon Anderson --- etc/warewulf.conf | 4 ---- 1 file changed, 4 deletions(-) diff --git a/etc/warewulf.conf b/etc/warewulf.conf index 43018879..d0a0c4db 100644 --- a/etc/warewulf.conf +++ b/etc/warewulf.conf @@ -9,16 +9,13 @@ warewulf: autobuild overlays: true host overlay: true syslog: false - datastore: "" dhcp: enabled: true - template: default range start: 192.168.200.50 range end: 192.168.200.99 systemd name: dhcpd tftp: enabled: true - tftproot: "" systemd name: tftp nfs: enabled: true @@ -32,4 +29,3 @@ nfs: mount options: defaults mount: false systemd name: nfs-server - From 6cfd028ee2c7bb593169c48ee3c943f64c727990 Mon Sep 17 00:00:00 2001 From: Jonathon Anderson Date: Wed, 24 Aug 2022 05:12:06 -0600 Subject: [PATCH 6/7] Initial commit: nodes.conf manpage Signed-off-by: Jonathon Anderson --- docs/man/man5/nodes.conf.5 | 22 ++++++++++++++++++++++ 1 file changed, 22 insertions(+) create mode 100644 docs/man/man5/nodes.conf.5 diff --git a/docs/man/man5/nodes.conf.5 b/docs/man/man5/nodes.conf.5 new file mode 100644 index 00000000..7bd965d2 --- /dev/null +++ b/docs/man/man5/nodes.conf.5 @@ -0,0 +1,22 @@ +.TH "NODES.CONF" "5" + +.SH NAME + +nodes.conf \- warewulf node configuration database + +.SH DESCRIPTION +.LP + +\fBnodes.conf\fP is the primary database file for all compute nodes +(and node profiles). It is a flat text YAML configuration file that is +managed by \fBwwctl(1)\fP. + +While manual editing of the \fBnodes.conf\fP file is possible and can +be useful, the internal structure of the file is subject to change +without notice between Warewulf versions. The recommended and only +supported mechanism for updating \fBnodes.conf\fP is via +\fBwwctl(1)\fP. + +.SH SEE ALSO + +\fBwwctl(1)\fP, \fBwwctl-nodes(1)\fP, \fBwwctl-profile(1)\fP From 247c61295ca7da60120a291b259ac7815b9ae718 Mon Sep 17 00:00:00 2001 From: Jonathon Anderson Date: Wed, 24 Aug 2022 06:15:36 -0600 Subject: [PATCH 7/7] Install new config file man pages Signed-off-by: Jonathon Anderson --- Makefile | 7 +++++-- warewulf.spec.in | 1 + 2 files changed, 6 insertions(+), 2 deletions(-) diff --git a/Makefile b/Makefile index 60ec87c6..c57250ba 100644 --- a/Makefile +++ b/Makefile @@ -164,6 +164,7 @@ files: all install -d -m 0755 $(DESTDIR)$(WWCONFIGDIR)/ipxe install -d -m 0755 $(DESTDIR)$(BASHCOMPDIR) install -d -m 0755 $(DESTDIR)$(MANDIR)/man1 + install -d -m 0755 $(DESTDIR)$(MANDIR)/man5 install -d -m 0755 $(DESTDIR)$(WWDOCDIR) install -d -m 0755 $(DESTDIR)$(FIREWALLDDIR) install -d -m 0755 $(DESTDIR)$(SYSTEMDDIR) @@ -190,7 +191,8 @@ files: all install -m 0644 include/systemd/warewulfd.service $(DESTDIR)$(SYSTEMDDIR) install -m 0644 LICENSE.md $(DESTDIR)$(WWDOCDIR) cp bash_completion.d/warewulf $(DESTDIR)$(BASHCOMPDIR) - cp man_pages/* $(DESTDIR)$(MANDIR)/man1/ + cp man_pages/*.1* $(DESTDIR)$(MANDIR)/man1/ + cp man_pages/*.5* $(DESTDIR)$(MANDIR)/man5/ install -m 0644 staticfiles/arm64.efi $(DESTDIR)$(WWDATADIR)/ipxe install -m 0644 staticfiles/x86_64.efi $(DESTDIR)$(WWDATADIR)/ipxe install -m 0644 staticfiles/x86_64.kpxe $(DESTDIR)$(WWDATADIR)/ipxe @@ -227,7 +229,8 @@ man_page: man_pages: man_page install -d man_pages ./man_page ./man_pages - cd man_pages; for i in wwctl*1; do echo "Compressing manpage: $$i"; gzip --force $$i; done + cp docs/man/man5/*.5 ./man_pages/ + cd man_pages; for i in wwctl*1 *.5; do echo "Compressing manpage: $$i"; gzip --force $$i; done config_defaults: vendor cmd/config_defaults/config_defaults.go cd cmd/config_defaults && go build -ldflags="-X 'github.com/hpcng/warewulf/internal/pkg/warewulfconf.ConfigFile=./etc/warewulf.conf'\ diff --git a/warewulf.spec.in b/warewulf.spec.in index 67d9261f..08ba6c50 100644 --- a/warewulf.spec.in +++ b/warewulf.spec.in @@ -122,6 +122,7 @@ getent group %{wwgroup} >/dev/null || groupadd -r %{wwgroup} %attr(-, root, root) %{_prefix}/lib/firewalld/services/warewulf.xml %attr(-, root, root) %{_unitdir}/warewulfd.service %attr(-, root, root) %{_mandir}/man1/wwctl* +%attr(-, root, root) %{_mandir}/man5/*.5* %attr(-, root, root) %{_datadir}/warewulf %dir %{_docdir}/warewulf