.\" $HeadURL$ $LastChangedRevision$
.\" vim: filetype=nroff
.\"
.TH PCMS 1 "ADE_APP_TOKEN_RELEASE_DATE_MAN"
.SH NAME
pcms \- poor man's configuration management system
.br
.ne 5
.SH SYNOPSIS
.B pcms
\*[ade_standard_synopsis_component]
[
.B \-\-update\-os
|
.B \-\-no\-update\-os
]
[
.B \-\-update\-site\-config
|
.B \-\-no\-update\-site\-config
]
[
.B \-\-make
|
.B \-\-no\-make
]
[
.B \-\-passes=\fInum\fR[\fB,...\fR]
]
[
.B \-\-plugins
|
.B \-\-no\-plugins
]
[
.B \-\-cleanup
|
.B \-\-no\-cleanup
]
[
.B \-\-config\-file=\fIfile\fB
]
[
.B \-\-site\-config\-dir=\fIdir\fB
]
[
.B \-\-
[
.I make\-options
]
[
.I make\-targets
]
]
.br
.ne 5
.SH DESCRIPTION
.B Pcms
updates the PCMS configuration module (see
.B pcms\fR(7)),
applies any available operating system updates,
runs
.B make\fR(1)
to align the system with the PCMS configuration module's specifications,
and runs any system-, site- or host-specific plugins.
Each of these tasks can be disabled by command-line options (see
.B OPTIONS
below) or by a suitable entry in PCMS's configuration file (see
.B CONFIGURATION
below).
.br
.ne 5
.SH CONFIGURATION
.B Pcms\fR's
configuration file, by default
.B \*[pcms_etc_prefix]/pcms.conf,
may contain blank lines, hash-led comments and assignments of the format
.I variable-name\fB=\fIvalue\fR.
The normal shell rules regarding quoting of values containing spaces, etc, apply (see
.B bash\fR(1)).
Some assignments are required; others are optional. A list of possible
assignments, descriptions of their purposes, their obligatoriness and any default values follow:
.TP 25
.B CLEANUP_FLAG=\fR{\fBtrue\fR|\fBfalse\fR}
determines whether temporary Makefiles that 
.B pcms
created are deleted by 
.B pcms 
when it exits.
(optional; defaults to
.B true\fR)
.TP
.B PLUGINS_FLAG=\fR{\fBtrue\fR|\fBfalse\fR}
determines whether
.B pcms
will execute site- and host-specific plugins.
(optional; defaults to
.B true\fR)
.TP
.B ENABLED_FLAG=\fR{\fBtrue\fR|\fBfalse\fR}
determines whether
.B pcms
should operate normally or exit immediately without taking any action.
(optional; defaults to
.B true\fR)
.TP
.B MAKE_FLAG=\fR{\fBtrue\fR|\fBfalse\fR}
determines where
.B pcms
should run
.B make\fR(1)
to align the system with the PCMS's configurations module's specifications or not.
(optional; defaults to
.B true\fR)
.TP
.B UPDATE_OS_FLAG=\fR{\fBtrue\fR|\fBfalse\fR}
determines whether
.B pcms
should apply any available operating system updates or not.
(optional; defaults to
.B true\fR)
.TP
.B UPDATE_SITE_CONFIG_FLAG=\fR{\fBtrue\fR|\fBfalse\fR}
determines whether
.B pcms
should update the PCMS configuration module (see 
.B pcms\fR(7))
or not.
(optional; defaults to
.B true\fR)
.TP
.B SITE_CONFIG_DIR=\fIdir
sets the location of the PCMS configurations module.
(optional; defaults to
.B \*[pcms_etc_prefix]/site\-config\fR)
.TP
.B SITE_CONFIG_FACILITY_MK=\fR{\fIfile\fR|\fIcmd\fR}
sets the path of the Makefile that specifies site-specific
recipes. If the path ends with `\fB|\fR' (a pipe) then it is
interpreted as a command to run to generate the Makefile.
(required; no default)
.TP
.B SITE_CONFIG_MASTER_HOST_DERIVER_CMD=\fIcmd\fR
sets the command used to determine the PCMS configuration module's repository master.
It is expected to be either `\fBsvn info
.I dir\fR'
(see 
.B svn\fR(1))
or `\fBcd
.I dir
.B && git config --get remote.origin.url\fR'
(see 
.B git\-config\fR(1))
piped into
.B sed\fR(1)
to extract the repository master's hostname.
(required; no default)
.TP
.B SITE_CONFIG_UPDATER_CMD=\fIcmd\fR
sets the command used to update the local copy of the PCMS configuration module with
any updates that are available on the repository master.
It is expected to be either `\fBsvn update
.I dir\fR'
(see
.B svn\fR(1))
or `\fBcd
.I dir
.B && git pull\fR'
(see
.B git\-pull\fR(1)).
(required; no default)
.PP
Values may contain the string `\fB%{SITE_CONFIG_DIR}\fR', which will be replaced
by value of
.B SITE_CONFIG_DIR\fR,
even if the latter's value has not been explicitly defined.
.br
.ne 5
.SH OPTIONS
Options provided on the command-line override the equivalent assignments in
.B pcms\fR's
configuration file.
\*[ade_standard_options_component]
.TP
.B \-\-update\-os
equivalent to the following assignment in
.B pcms\fR's
configuration file:
.IP
.B UPDATE_OS_FLAG=true
.TP
.B \-\-no\-update\-os
equivalent to the following assignment in
.B pcms\fR's
configuration file:
.IP
.B UPDATE_OS_FLAG=false
.TP
.B \-\-plugins
equivalent to the following assignment in
.B pcms\fR's
configuration file:
.IP
.B PLUGINS_FLAG=true
.TP
.B \-\-no\-plugins
equivalent to the following assignment in
.B pcms\fR's
configuration file:
.IP
.B PLUGINS_FLAG=false
.TP
.B \-\-update\-site\-config
equivalent to the following assignment in
.B pcms\fR's
configuration file:
.IP
.B UPDATE_SITE_CONFIG_FLAG=true
.TP
.B \-\-no\-update\-site\-config
equivalent to the following assignment in
.B pcms\fR's
configuration file:
.IP
.B UPDATE_SITE_CONFIG_FLAG=false
.TP
.B \-\-make
equivalent to the following assignment in
.B pcms\fR's
configuration file:
.IP
.B MAKE_FLAG=true
.TP
.B \-\-no\-make
equivalent to the following assignment in
.B pcms\fR's
configuration file:
.IP
.B MAKE_FLAG=false
.TP
.B \-\-passes=\fInum\fR[\fB,...\fR]
.B Pcms
runs in four passes:
in pass #3 it generates helper Makefiles for generated files (i.e. files whose content is generated by a script);
in pass #2 it loads those helper Makefiles and runs those recipes to generate those files;
in pass #1 it generates helper Makefile for other types of files (e.g. files that just need to be copied, standard record-based files like ~root/.ssh/authorized_keys);
in pass #0 it loads those helper Makefiles and runs those recipes to generate those files.
Note first run pass is pass #3 and the last run pass is pass #0; this is intended to ensure that the function of each pass does not change when new passes are added.
.TP
.B \-\-cleanup
equivalent to the following assignment in
.B pcms\fR's
configuration file:
.IP
.B CLEANUP_FLAG=true
.TP
.B \-\-no\-cleanup
equivalent to the following assignment in
.B pcms\fR's
configuration file:
.IP
.B CLEANUP_FLAG=false
.TP
.B \-\-config\-file=\fIfile\fB
sets the location of PCMS's main configuration file.
.TP
.B \-\-site\-config\-dir=\fIdir\fB
equivalent to the following assignment in
.B pcms\fR's
configuration file:
.IP
.B SITE_CONFIG_DIR=\fIdir\fB
.br
.ne 5
.SH EXIT STATUS
On success
.B pcms
returns zero. On failure it returns non-zero and displays a diagnostic
message.
.br
.ne 5
.SH FILES
Too many to mention.
.br
.ne 5
.SH ENVIRONMENT VARIABLES
None.
.br
.ne 5
.SH EXAMPLES
None.
.br
.ne 5
.SH CAVEATS
See
.B pcms\fR(7).
.br
.ne 5
.SH STANDARDS
This manual page documents version ADE_APP_TOKEN_RELEASE_ID of
.B pcms\fR.
.br
.ne 5
.SH SEE ALSO
apt-get(8), bash(1), git\-config(1), git\-pull(1), git\-status(1), make(1), pcms(7), pcms-config(1), sed(1), svn(1)
.br
.ne 5
.SH AUTHOR
ADE_APP_TOKEN_AUTHOR_NAME <ADE_APP_TOKEN_AUTHOR_EMAIL>
.br
.ne 5
.SH COPYRIGHT & DISTRIBUTION POLICY
Copyright (C) 2016-ADE_APP_TOKEN_RELEASE_YEAR ADE_APP_TOKEN_AUTHOR_NAME
\*[ade_standard_copyright_component]