File: caspar.html

package info (click to toggle)
caspar 20180315-2
links: PTS
area: main
in suites: buster
size: 848 kB
sloc: sh: 566; makefile: 124
file content (557 lines) | stat: -rw-r--r-- 20,436 bytes
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<!-- Copyright (c) 2018 Joost van Baal-Ilić -->
<head>
<meta name="keywords" content="manual">
<style type="text/css">
/* START aephea.base.css */
body
{ text-align: justify;
margin-left: 0%;
margin-right: 0%;
}
a:link { text-decoration: none; }
a:active { text-decoration: none; }
a:visited { text-decoration: none; }
a:link { color: #1111aa; }
a:active { color: #1111aa; }
a:visited { color: #111166; }
a.local:link { color: #11aa11; }
a.local:active { color: #11aa11; }
a.local:visited { color: #116611; }
a.intern:link { color: #1111aa; }
a.intern:active { color: #1111aa; }
a.intern:visited { color: #111166; }
a.extern:link { color: #aa1111; }
a.extern:active { color: #aa1111; }
a.extern:visited { color: #661111; }
a.quiet:link { color: black; }
a.quiet:active { color: black; }
a.quiet:visited { color: black; }
div.verbatim
{ font-family: monospace;
margin-top: 1em;
margin-bottom: 1em;
font-size: 10pt;
margin-left: 2em;
white-space: pre;
}
div.indent
{ margin-left: 8%;
margin-right: 0%;
}
.right { text-align: right; }
.left { text-align: left; }
.nowrap { white-space: nowrap; }
.item_leader
{ position: relative;
margin-left: 8%;
}
.item_compact { position: absolute; vertical-align: baseline; }
.item_cascade { position: relative; }
.item_leftalign { text-align: left; }
.item_rightalign
{ width: 2em;
text-align: right;
}
.item_compact .item_rightalign
{ position: absolute;
width: 52em;
right: -2em;
text-align: right;
}
.item_text
{ position: relative;
margin-left: 3em;
}
.smallcaps { font-size: smaller; text-transform: uppercase }
/* END aephea.base.css */
body { font-family: "Garamond", "Gill Sans", "Verdana", sans-serif; }
body
{ text-align: justify;
margin-left: 8%;
margin-right: 8%;
}
</style>
<title>caspar</title>
</head>
<body>
<p style="text-align:right">
15 мар 2018&nbsp;&nbsp;&nbsp;
<a class="local" href="caspar.ps"><b>caspar</b></a>
20180315
</p>
<div class=" itemize " style="margin-top:1em; font-size:100%">
<div class=" item_compact"><div class=" item_rightalign nowrap " style="right:-3em">1.</div></div>
<div class=" item_text " style="margin-left:4em">
<a class="intern" href="#name">NAME</a>
</div>
<div class=" item_compact"><div class=" item_rightalign nowrap " style="right:-3em">2.</div></div>
<div class=" item_text " style="margin-left:4em">
<a class="intern" href="#synopsis">SYNOPSIS</a>
</div>
<div class=" item_compact"><div class=" item_rightalign nowrap " style="right:-3em">3.</div></div>
<div class=" item_text " style="margin-left:4em">
<a class="intern" href="#description">DESCRIPTION</a>
</div>
<div class=" item_compact"><div class=" item_rightalign nowrap " style="right:-3em">4.</div></div>
<div class=" item_text " style="margin-left:4em">
<a class="intern" href="#usage">USAGE</a>
</div>
<div class=" item_compact"><div class=" item_rightalign nowrap " style="right:-3em">5.</div></div>
<div class=" item_text " style="margin-left:4em">
<a class="intern" href="#variables">VARIABLES</a>
</div>
<div class=" item_compact"><div class=" item_rightalign nowrap " style="right:-3em">6.</div></div>
<div class=" item_text " style="margin-left:4em">
<a class="intern" href="#examples">EXAMPLES</a>
</div>
<div class=" item_compact"><div class=" item_rightalign nowrap " style="right:-3em">7.</div></div>
<div class=" item_text " style="margin-left:4em">
<a class="intern" href="#files">FILES</a>
</div>
<div class=" item_compact"><div class=" item_rightalign nowrap " style="right:-3em">8.</div></div>
<div class=" item_text " style="margin-left:4em">
<a class="intern" href="#environment">ENVIRONMENT</a>
</div>
<div class=" item_compact"><div class=" item_rightalign nowrap " style="right:-3em">9.</div></div>
<div class=" item_text " style="margin-left:4em">
<a class="intern" href="#bugs">BUGS</a>
</div>
<div class=" item_compact"><div class=" item_rightalign nowrap " style="right:-3em">10.</div></div>
<div class=" item_text " style="margin-left:4em">
<a class="intern" href="#trivia">TRIVIA</a>
</div>
<div class=" item_compact"><div class=" item_rightalign nowrap " style="right:-3em">11.</div></div>
<div class=" item_text " style="margin-left:4em">
<a class="intern" href="#author">AUTHOR</a>
</div>
<div class=" item_compact"><div class=" item_rightalign nowrap " style="right:-3em">12.</div></div>
<div class=" item_text " style="margin-left:4em">
<a class="intern" href="#seealso">SEE ALSO</a>
</div>
</div>

<a name="name"></a>
<h2>NAME</h2>
caspar - Makefile snippets for common tasks

<a name="synopsis"></a>
<h2>SYNOPSIS</h2>
In a Makefile, write either
<div class="verbatim">
  include caspar/mk/caspar.mk
</div>
or
<div class="verbatim">
  include caspar/mk/docbook.mk
</div>
or
<div class="verbatim">
  include caspar/mk/pod.mk
</div>
.

<a name="description"></a>
<h2>DESCRIPTION</h2>
Caspar offers Makefile snippets for common tasks, like installing
(configuration) files, or typesetting LaTeX, DocBook XML and DocBook SGML
documents.
<p style="margin-bottom:0" class="asd_par">
The typesetting functionality is delivered by <i>docbook.mk</i> and <i>pod.mk</i>.
This is documented in <a class="local sibling" href="caspar-typesetting.html">caspar-typesetting(7)</a>.
</p> <p style="margin-bottom:0" class="asd_par">
The installing-stuff functionality is delivered by <i>caspar.mk</i>.
(That's what the rest of the manual will talk about.) It enables one to run
'make install' from within a tree which typically holds configuration files,
managed using Subversion (or git or any other version control system, for that
matter).
</p> <p style="margin-bottom:0" class="asd_par">
It is useful in cases like this: all configuration files of some host are under
version control, and, after commiting a change to CVS, you want to be able to
easily install the new configuration file on the host.
</p> <p style="margin-bottom:0" class="asd_par">
With <b>caspar</b>, all you have to do is specify the hostname in one place, and
specify the name of the target directory in each CVS directory.
</p> <p style="margin-bottom:0" class="asd_par">
It is comparable with other tools for Unix system administrators like
puppet and cfengine. Main difference: the caspar code consists of less than
100 lines of GNU Make.
</p>

<a name="usage"></a>
<h2>USAGE</h2>
Within a CVS tree, create a file <i>include/install.mk</i>, with contents like
e.g.
<div class="verbatim">
 csp_UHOST = root@some.host.somewhere
 include caspar/mk/caspar.mk
</div>
. Within each other directory of the CVS tree which holds files, create a
Makefile, which looks like e.g.
<div class="verbatim">
 csp_DIR = /some/dir/ectory/
 include ../../include/install.mk
</div>
.
If you'd like to use the <i>install-recursive</i> target too, in directories
which hold subdirectories (but not files), you'll have to create a Makefile
which looks something like
<div class="verbatim">
 include ../../include/install.mk
</div>
. From within the CVS tree, one can call:
<div class="verbatim">
  make &lt;filename&gt;-diff
  make &lt;filename&gt;-install
  make diff
  make install
  make load
  make
  make install-recursive
</div>
Calling <tt>make &lt;filename&gt;-diff</tt> shows the diff between the local file
and the file as currently installed on the remote location.
Calling <tt>make install</tt> (or <tt>make</tt>) now will scp all files in the current
directory to the remote location. The <i>install-recursive</i> target descends
down the tree, and calls <tt>make install</tt> in each subdirectory.
<p style="margin-bottom:0" class="asd_par">
Of course, you'll have to be able to ssh directly as root to the remote host to
get this working (if you'd like to use <tt>csp_UHOST =
root@some.host.somewhere</tt>). If you don't like this, and would like to have a
<tt>PermitRootLogin no</tt> in your <tt>/etc/ssh/sshd_config</tt>, you can use
csp_sucp(1). See below.
</p>

<a name="variables"></a>
<h2>VARIABLES</h2>
<p style="margin-bottom:0" class="asd_par">
The variables one can set in a calling Makefile are:
<div class=" itemize " style="margin-top:1em; font-size:100%">
<div class=" item_cascade"><div class=" item_leftalign nowrap " ><tt>csp_UHOST</tt></div></div>
<div class=" item_text " style="margin-left:2em">
user@host, reachable using <tt>$(csp_PUSH)</tt> (which
is scp by default)
</div>
<div class=" item_cascade"><div class=" item_leftalign nowrap " ><tt>csp_UHOSTS</tt></div></div>
<div class=" item_text " style="margin-left:2em">
space separated list of user@host items, reachable
using <tt>$(csp_PUSH)</tt>
</div>
<div class=" item_cascade"><div class=" item_leftalign nowrap " ><tt>csp_DIR</tt></div></div>
<div class=" item_text " style="margin-left:2em">
directory on host, reachable using function
<tt>$(csp_PUSH)</tt>
</div>
<div class=" item_cascade"><div class=" item_leftalign nowrap " ><tt>csp_PUSH</tt></div></div>
<div class=" item_text " style="margin-left:2em">
make function for pushing files to remote location.
Usually, this is a wrapper around a script or
program. The function will be passed 4 arguments:
			 <i>[user@]host</i>, remote <i>directory</i> and local
<i>filename</i>.
<i>[user@]host</i> will be set
to all elements of <tt>$(csp_UHOSTS)</tt>;
<i>directory</i> will be set to <tt>$(csp_DIR)</tt>.
Currently, <tt>$(csp_scp_FUNC)</tt>, <tt>$(csp_cp_FUNC)</tt>
and <tt>$(csp_sucp_FUNC)</tt> are supported as push
plugins. If <tt>csp_PUSH</tt> is unset, the default
<tt>$(csp_scp_FUNC)</tt> is used.
</div>
<div class=" item_cascade"><div class=" item_leftalign nowrap " ><tt>csp_LOAD</tt></div></div>
<div class=" item_text " style="margin-left:2em">
the `load' target depends upon these targets.
</div>
<div class=" item_cascade"><div class=" item_leftalign nowrap " ><tt>csp_BUILD</tt></div></div>
<div class=" item_text " style="margin-left:2em">
the `build' target depends upon these targets.
</div>
<div class=" item_cascade"><div class=" item_leftalign nowrap " ><tt>csp_CP</tt></div></div>
<div class=" item_text " style="margin-left:2em">
cp binary, just "cp" by default
</div>
<div class=" item_cascade"><div class=" item_leftalign nowrap " ><tt>csp_SCP</tt></div></div>
<div class=" item_text " style="margin-left:2em">
scp binary, just "scp" by default
</div>
<div class=" item_cascade"><div class=" item_leftalign nowrap " ><tt>csp_SUCP</tt></div></div>
<div class=" item_text " style="margin-left:2em">
script wrapping sudo in ssh, "csp_sucp" by default
</div>
<div class=" item_cascade"><div class=" item_leftalign nowrap " ><tt>csp_EXTRAFILES</tt></div></div>
<div class=" item_text " style="margin-left:2em">
extra files which should be installed.
Can be used to include files starting with a dot.
</div>
<div class=" item_cascade"><div class=" item_leftalign nowrap " ><tt>csp_TABOOFILES</tt></div></div>
<div class=" item_text " style="margin-left:2em">
files which should never be installed. Set to
<tt>Makefile .%.swp %~ #%# pod2htmd.tmp pod2htmi.tmp</tt> by default.
</div>
<div class=" item_cascade"><div class=" item_leftalign nowrap " ><tt>csp_TABOOFILES_ADD</tt></div></div>
<div class=" item_text " style="margin-left:2em">
extra files which should never be installed;
added to list in <tt>csp_TABOOFILES</tt>.
</div>
<div class=" item_cascade"><div class=" item_leftalign nowrap " ><tt>csp_TABOOFILES_SKIP</tt></div></div>
<div class=" item_text " style="margin-left:2em">
files which should be installed, even if
in initial <tt>csp_TABOOFILES</tt> list. Removed from <tt>csp_TABOOFILES</tt>
list.
</div>
<div class=" item_cascade"><div class=" item_leftalign nowrap " ><tt>csp_TABOODIRS</tt></div></div>
<div class=" item_text " style="margin-left:2em">
directories to exclude in install-recursive target.
set to <tt>CVS .svn</tt> by default.
</div>
<div class=" item_cascade"><div class=" item_leftalign nowrap " ><tt>csp_TABOODIRS_ADD</tt>, <tt>csp_TABOODIRS_SKIP</tt></div></div>
<div class=" item_text " style="margin-left:2em">
see
<tt>csp_TABOOFILES</tt> equivalents.
</div>
<div class=" item_cascade"><div class=" item_leftalign nowrap " ><tt>csp_UHOSTS_SUBSET</tt></div></div>
<div class=" item_text " style="margin-left:2em">
override csp_UHOSTS: don't push to csp_UHOSTS, but
to the intersection of this space separated list of user@host items and
csp_UHOSTS.
</div>
</div>
</p>
<p style="margin-bottom:0" class="asd_par">
The following variables might get phased out or removed soonish:
<div class=" itemize " style="margin-top:1em; font-size:100%">
<div class=" item_cascade"><div class=" item_leftalign nowrap " ><tt>csp_CPFLAGS</tt></div></div>
<div class=" item_text " style="margin-left:2em">
extra arguments to pass to cp invocation, none by
default
</div>
<div class=" item_cascade"><div class=" item_leftalign nowrap " ><tt>csp_SCPFLAGS</tt></div></div>
<div class=" item_text " style="margin-left:2em">
extra arguments to pass to scp invocation, e.g.
'<tt>-i .ssh/id_rsa-root</tt>'
</div>
</div>
</p>

<a name="examples"></a>
<h2>EXAMPLES</h2>
<p style="margin-bottom:0" class="asd_par">
Some examples:
</p>
<p style="margin-bottom:0"><b>Using csp_UHOST</b><br>
This is the simplest way to use caspar. <i>Makefile</i> is
<div class="verbatim">
  csp_UHOST = root@some.host.somewhere
  csp_DIR = /etc/
  include caspar/mk/caspar.mk
</div>
Now, running "make" will scp all files in the current directory to
<tt>root@some.host.somewhere:/etc/</tt>.
</p>
<p style="margin-bottom:0"><b>More hosts, not scp but sudo via ssh: using csp_PUSH</b><br>
<i>Makefile</i> is
<div class="verbatim">
  csp_UHOSTS = root@some.host.somewhere root@some.other.host
  csp_PUSH = $(csp_sucp_FUNC)
  csp_DIR = /etc/
  include caspar/mk/caspar.mk
</div>
Now, running "make" will use csp_sucp(1) to install all files in the current
directory to both root@some.host.somewhere:/etc/ and
root@some.other.host:/etc/. If a file named <tt>fstab</tt> is present in the
current directory, running "make fstab-install" will just install that one
file.
If you need to sudo(1) to another user on the remote host, add something like
<div class="verbatim">
 csp_XARG = postgres
</div>
. (If such a username is not supplied, sudo (and csp_sucp) use the default:
root.)
</p>
<p style="margin-bottom:0"><b>Overriding csp_UHOSTS: csp_UHOSTS_SKIP</b><br>
If one or some of your hosts are temporarily unavailable, and you'd like to
push your files to the hosts which are alive, you can temporarily override your
csp_UHOSTS. E.g., when some.other.host is not available:
<div class="verbatim">
 % cat Makefile 
 csp_UHOSTS = root@some.host.somewhere root@some.other.host
 csp_DIR = /etc/
 include caspar/mk/caspar.mk

 % make install csp_UHOSTS_SKIP=root@some.other.host
 scp hosts root@some.host.somewhere:/etc/
 scp fstab root@some.host.somewhere:/etc/
</div>
</p>
<p style="margin-bottom:0"><b>Overriding csp_UHOSTS in a smart way: csp_UHOSTS_SUBSET. Using multiple
groups of hosts. Recursive make made easy.</b><br>
If you have lots of subdirectories holding information for lots of groups of
hosts, while this run you just want to install for a small group (or 1) hosts,
csp_UHOSTS_SUBSET is useful.
Suppose your casparized tree looks like
<div class="verbatim">
 Makefile

 apache/include/install.mk
 apache/etc/apache2/Makefile
 apache/etc/apache2/envvars

 php/include/install.mk
 php/etc/php4/apache/Makefile
 php/etc/php4/apache/php.ini

 grub/include/install.mk
 grub/boot/grub/Makefile
 grub/boot/grub/menu.lst
 logrotate/include/install.mk
 logrotate/etc/Makefile
 logrotate/etc/logrotate.conf

 nrpe/include/install.mk
 nrpe/debian/etc/default/Makefile
 nrpe/debian/etc/default/nagios-nrpe-server
</div>
The file <i>apache/etc/apache2/Makefile</i> is:
<div class="verbatim">
 csp_DIR = /etc/apache2/
 include ../../include/install.mk
</div>
(all other <i>Makefile</i>s are similar).
The file <i>apache/include/install.mk</i> is
<div class="verbatim">
 csp_UHOSTS = root@a root@b
 include caspar/mk/caspar.mk
</div>
The file <i>php/include/install.mk</i> is the same. The files
<i>grub/include/install.mk</i> and <i>logrotate/include/install.mk</i> are
<div class="verbatim">
 csp_UHOSTS = root@d root@e root@f root@g
 include caspar/mk/caspar.mk
</div>
The file <i>nrpe/include/install.mk</i> is
<div class="verbatim">
 csp_UHOSTS = root@d root@e root@f root@n
 include caspar/mk/caspar.mk
</div>
The toplevel <i>Makefile</i> is
<div class="verbatim">
 dirs = $(patsubst %/Makefile,%,$(shell find * -mindepth 1
  -name Makefile))

 all:
     for i in $(dirs); do $(MAKE) -$(MAKEFLAGS) -C $$i; done

 install
     for i in $(dirs); do $(MAKE) -$(MAKEFLAGS) -C $$i install; done

 load
     for i in $(dirs); do $(MAKE) -$(MAKEFLAGS) -C $$i load; done
</div>
(we don't feel like sticking a <i>Makefile</i> in all non-leaf nodes of our tree).
</p> <p style="margin-bottom:0" class="asd_par">
Now, when running "<tt>csp_UHOSTS_SUBSET='root@e root@f root@m root@n' make</tt>"
in the toplevel, caspar just takes the intersection of csp_UHOSTS_SUBSET and
csp_UHOSTS for each csp_UHOSTS list. So, caspar will not push anything for
<i>apache/</i> and <i>php/</i>. The files <i>grub/boot/grub/menu.lst</i> and
<i>logrotate/etc/logrotate.conf</i> will get pushed to <tt>root@e</tt> and
<tt>root@f</tt> only. The file <i>nrpe/debian/etc/default/nagios-nrpe-server</i>
will get pushed to <tt>root@e</tt>, <tt>root@f</tt> and <tt>root@n</tt>.
</p> <p style="margin-bottom:0" class="asd_par">
This is often better than just overriding csp_UHOSTS on the commandline (or in
your shell's environment): if the intersection of the original csp_UHOSTS and
your new csp_UHOSTS is empty, chances are big you've just forgotten to clean
your environment.
</p>
<p style="margin-bottom:0"><b>Creating remote directories if needed</b><br>
<i>Makefile</i> is
<div class="verbatim">
  csp_DIR = /some/dir/ectory/
  csp_PUSH = $(csp_scpmkdir_FUNC)
  csp_UHOST = root@some.host.somewhere
  include caspar/mk/caspar.mk
</div>
Now, before calling scp, caspar will run 'mkdir -p' to create any missing
remote directories.
</p>
<p style="margin-bottom:0"><b>Using csp_CP and csp_LOAD</b><br>
<i>username/etc/Makefile</i> is
<div class="verbatim">
  csp_UHOST = dummy
  csp_PUSH = $(csp_cp_FUNC)
  csp_DIR = $(HOME)/etc/
  csp_LOAD = crontab-load
  include ../include/install.mk

  crontab-load = crontab $(csp_DIR)/crontab
</div>
while <i>../include/install.mk</i> is just
<div class="verbatim">
  include caspar/mk/caspar.mk
</div>
.
Setting <tt>csp_PUSH</tt> to <tt>$(csp_cp_FUNC)</tt> causes cp(1) to get executed
by "make install" (not scp(1)).
Setting <tt>csp_LOAD</tt> causes "make load" to execute the crontab command. Just
running "make" is OK too, since "make" calls both "make install" and "make
load".
</p>
<p style="margin-bottom:0"><b>Using csp_DIR, csp_LOAD and install(1)</b><br>
To install a file on the local host, create e.g. a file <i>etc/uruk/Makefile</i>
like:
<div class="verbatim">
  csp_UHOST = dummy
  csp_DIR = /etc/uruk/
  csp_PUSH = $(csp_install_FUNC)
  csp_LOAD = uruk-load

  include caspar/mk/caspar.mk

  uruk-load = sudo invoke-rc.d uruk force-reload
</div>
</p>
<p style="margin-bottom:0"><b>Using csp_DIR and csp_LOAD, take 2</b><br>
<i>etc/Makefile</i> is
<div class="verbatim">
  csp_DIR = /etc/
  csp_LOAD = aliases-load
  include ../include/install.mk

  aliases-load = $(csp_SSH) $1 "cd /etc &amp;&amp; postalias aliases; postfix reload"
</div>
while <i>../include/install.mk</i> is
<div class="verbatim">
  csp_UHOST = root@some.host.somewhere
  include caspar/mk/caspar.mk
</div>
</p>
<p style="margin-bottom:0"><b>Building files locally</b><br>
Note: csp_BUILD is deprecated. You should not use it.
If you'd like to build some files locally from local sources, before installing
the just built files, do e.g.:
<div class="verbatim">
 csp_UHOST = root@some.host.somewhere
 csp_DIR = /etc/
 csp_EXTRAFILES = sshd_config
 csp_TABOOFILES_ADD = sshd_config.m4

 include caspar/mk/caspar.mk

 sshd_config: sshd_config.m4
     m4 $&lt; &gt; $@
</div>
List all source files in csp_TABOOFILES_ADD: this way, they won't get installed
on the csp_UHOST.
</p>
<p style="margin-bottom:0"><b>Using csp_sucp_FUNC and csp_LOAD</b><br>
If you'd like to use csp_sucp and want a `load' target, do something like:
<div class="verbatim">
 csp_PUSH = $(csp_sucp_FUNC)
 csp_UHOST = foobar.example.com
 csp_DIR = /etc/uruk/
 csp_LOAD = rc-load

 include caspar/mk/caspar.mk

 rc-load = $(csp_SSH) $1 sudo invoke-rc.d uruk force-reload
</div>
</p>