.\" $HeadURL$ $LastChangedRevision$
.\" vim: filetype=nroff
.\"
.TH PCMS 7 "ADE_APP_TOKEN_RELEASE_DATE_MAN"
.SH NAME
PCMS \- an introduction
.br
.ne 5
.SH DESCRIPTION
PCMS is a lightweight configuration management system based on GNU
.B make\fR(1). It was born out of a frustration with Puppet
(see 
.B puppet\fR(8)).
.PP
PCMS performs the following tasks in this order:
.IP 1.
update the PCMS configuration module using commands
specified in PCMS's main configuration file
.IP 2.
apply any available operating system updates
.IP 3.
run 
.B make\fR(1)
to align the system with the configuration module's specifications
.IP 4.
run any system-m site- or host-specific plugins.
.PP
Each of these tasks can be disabled by command-line options or
by a suitable entry in PCMS's configuration file (see
.B pcms\fR(1)).
.PP
PCMS consists of the PCMS software distribution and a PCMS configuration module.
The PCMS software distribution consists of:
.TP 25
.B pcms\fR(1)
the command to perform the above-listed tasks
.TP
.B \*[pcms_etc_prefix]/pcms.conf
PCMS's main configuration file
.TP
.B \*[pcms_share_prefix]/makefiles/facilities/
Makefiles for configuring various system facilities, e.g. 
package repository access, the network, the desktop environment, the audio subsystem.
.TP
.B \*[pcms_share_prefix]/makefiles/methods/
helper Makefiles for the generation of individual records in one-record-per-line configuration files, e.g.
a single line in
.B /etc/hosts
(see
.B hosts\fR(7)).
.TP
.B \*[pcms_share_prefix]/makefiles/files/
helper Makefiles for assembling individual records (see above) into whole files, e.g.
.B /etc/hosts
(see
.B hosts\fR(7)).
.TP
.B \*[pcms_share_prefix]/files/\fR
facility-specific configuration files, e.g.
.B main.cf
(see
.B postconf\fR(5)).
.PP
There are other files in the PCMS software distribution, e.g. helper
scripts, man pages) but the locations and contents of these are
outside the scope of this introduction.
.PP
The PCMS configuration module, which is site- and/or host-specific  
and must be written by the user, should consist of:
.TP 25
.I site\-config\-dir\fB/makefiles/facilities/
a set of site-/host-specific symlinks (see
.B symlinks\fR(7))
to the facility Makefiles
provided by the PCMS software distribution
.TP
.I site\-config\-facility\-mk
A site-/site-specific Makefile or Makefile-generator. If it is a
Makefile-generator, then it is expected to generate Makefile content
based on the system's hostname (see
.B hostname \fR(5)).
.TP
.I site\-config\-dir\fB/files/
site-specific (but not host-specific) configuration files for the various facilities; these override
those in
.B \*[pcms_share_prefix]/files/\fR.
.TP
.I site\-config\-dir\fB/hosts/\fIhostname\fB/files/
host-specific configuration files for the various facilities; these override
those in 
.I site\-config\-dir\fB/files/\fR.
.TP
.I site\-config\-dir\fB/plugins/
site-specific (but not host-specific) plugins.
.TP
.I site\-config\-dir\fB/hosts/\fIhostname\fB/plugins/
host-specific plugins.
.PP
The location of
.I site\-config\-dir
can be defined in PCMS's main configuration file but defaults to
.B \*[pcms_etc_prefix]/site\-config\fR.
There is no default for
.I site\-config\-facility\-mk
and therefore must be defined in PCMS's main configuration file.
.PP
The PCMS configuration module should be stored under version control, e.g. Subversion or Git. 
Various parameters
related to version control, e.g. the version control tool, the URL 
of the master repository, must be specified in PCMS's main configuration file.
.br
.ne 5
.SH CAVEATS
Currently, PCMS's facility Makefiles are not stable.
.PP
Currently, PCMS is Debian-specific.
.PP
Currently, PCMS's documentation is inadequate.
.br
.ne 5
.\" STANDARDS is not relevant for this particular man page.
.\" .SH STANDARDS
.\" This manual page documents version ADE_APP_TOKEN_RELEASE_ID of
.\" .B pcms\fR.
.\" .br
.\" .ne 5
.SH SEE ALSO
git(1), hosts(5), make(1), pcms(1), postconf(5), puppet(8), 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]