diff options
author | Sean Whitton <spwhitton@spwhitton.name> | 2021-03-02 18:59:06 -0700 |
---|---|---|
committer | Sean Whitton <spwhitton@spwhitton.name> | 2021-03-02 18:59:06 -0700 |
commit | 40fdc8d6f232cfb2980b6cd9c5c6abde74f74515 (patch) | |
tree | 6abeb8a93b4a977b86d140f843e8e73e45266c75 /doc/introduction.rst | |
parent | 067dce0b24f336019f6a5324bb2d5b06a9d6bf21 (diff) | |
download | consfigurator-40fdc8d6f232cfb2980b6cd9c5c6abde74f74515.tar.gz |
move most of README into the manual
Signed-off-by: Sean Whitton <spwhitton@spwhitton.name>
Diffstat (limited to 'doc/introduction.rst')
-rw-r--r-- | doc/introduction.rst | 141 |
1 files changed, 141 insertions, 0 deletions
diff --git a/doc/introduction.rst b/doc/introduction.rst index 1b1e85b..e62f6b6 100644 --- a/doc/introduction.rst +++ b/doc/introduction.rst @@ -1,6 +1,120 @@ Introduction ============ +Try it out / quick start +------------------------ + +1. Install Consfigurator: :ref:`Installation`. + +2. Create a new directory ``consfig`` somewhere where ASDF will pick it up, + such as ``~/common-lisp/consfig``. + +3. Define a Lisp system which represents your configuration. + + ~/common-lisp/consfig/com.example.consfig.asd:: + + (asdf:defsystem :com.example.consfig + :serial t + :depends-on (#:consfigurator #:cl-interpol) + :components ((:file "package") + (:file "consfig"))) + + ~/common-lisp/consfig/package.lisp:: + + (in-package :cl-user) + + (defpackage :com.example.consfig + (:use #:cl #:consfigurator #:alexandria) + (:local-nicknames (#:file #:consfigurator.property.file) + (#:cmd #:consfigurator.property.cmd) + (#:data.pgp #:consfigurator.data.pgp))) + +4. Define some hosts and deployments. + + ~/common-lisp/consfig/consfig.lisp:: + + (in-package :com.example.consfig) + (in-consfig "com.example.consfig") + (named-readtables:in-readtable :interpol-syntax) + + (try-register-data-source + :pgp :location #P"/path/to/com.example.consfig.gpg") + + (defhost athena.example.com + (:deploy (:ssh (:sudo :as "spwhitton@athena.example.com") :debian-sbcl)) + "Web and file server." + (file:has-content "/etc/foo" '("these" "are" "my" "lines")) + (file:contains-lines "/etc/some.conf" '("FOO=bar"))) + + Here, "spwhitton" is my username on athena; we have to tell Consfigurator + what user it will be when it tries to sudo, so it knows whose password it + needs. If you have passwordless sudo access configured, you can skip the + ``:AS`` keyword parameter and its argument. + +5. Get a Lisp REPL started up -- ``M-x slime`` in Emacs or ``sbcl`` at a shell + prompt. Evaluate ``(asdf:load-system "consfigurator")``. + +6. When it's asked to use sudo to become root, Consfigurator will query your + registered sources of secrets to try to find the password it will need to + give to sudo. You can easily write code to let Consfigurator query your + own sources of secrets, but for the purposes of this guide we'll use the + simple, PGP-based secrets source included with Consfigurator. Unless + you've passwordless sudo access set up on athena, evaluate something like + this to initialise the store:: + + (consfigurator.data.pgp:set-data #P"/path/to/com.example.consfig.gpg" + "--user-passwd--athena.example.com" + "spwhitton" + "s3cre+") + +7. Now you can evaluate ``(asdf:load-system "com.example.consfig")`` followed + by ``(in-package :com.example.consfig)`` (or ``C-c ~`` in Emacs). In the + future, now the secrets store exists, you can start with this step. + +8. You should now be able to evaluate ``(athena.example.com)`` to deploy + properties to athena, using the connection chain of SSH, sudo and then + handing over to a remote Lisp image. + +Other things to try +~~~~~~~~~~~~~~~~~~~ + +Note that some of these violate some of the ideas of declarative configuration +management, because they apply individual properties without updating the +definitions of hosts. Sometimes that's the right thing to do, though, and +Consfigurator makes it easy to reuse your property definitions in these +non-declarative ways. + +Try deploying properties to athena using a different connection type +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +Evaluate something like:: + + (deploy :ssh athena.example.com) + +Apply a security update to all your systems ++++++++++++++++++++++++++++++++++++++++++++ + +It's useful to be able to quickly apply a security update across multiple +machines without otherwise interacting with their configuration. Supposing +you have defined a variable ``*ALL-MY-SERVERS*`` which is a list hosts defined +with ``DEFHOST``, you can evaluate:: + + (dolist (server *all-my-servers*) + (deploy-these :ssh server + (cmd:single "apt-get update && apt-get upgrade openssl"))) + +Regex replace a file across hosts ++++++++++++++++++++++++++++++++++ + +With ``*ALL-MY-SERVERS*`` as in the previous example,:: + + (dolist (server *all-my-servers*) + (deploy-these :ssh server + (file:regex-replace-lines "/etc/baz" #?/foo/ "bar"))) + +(relies on CL-INTERPOL syntax being enabled, as it is in the example consfig +above) + Concepts and terminology ------------------------ @@ -135,3 +249,30 @@ recommended package nicknaming schemes for use in consfigs, e.g.:: (:local-nicknames (#:file #:consfigurator.property.file) (#:cmd #:consfigurator.property.cmd) (#:data.pgp #:consfigurator.data.pgp))) + +Portability and stability +------------------------- + +- **Consfigurator is still stabilising and so there may be lots of breaking + changes.** + +- All of the code should be portable ANSI Common Lisp, but little to no + testing is done by the author on implementations other than SBCL, so testing + and portability patches are welcome. + +- Little attempt is made by the author to support systems other than Debian + GNU/Linux, but again, portability patches are welcome, and the design of + Consfigurator should enable supporting other systems. + +Credits +------- + +Many of the good ideas here come straight from Joey Hess's Propellor_. I'm +working on Consfigurator because I think Propellor is great, but wanted to add +Consfigurator's POSIX-type connections and arbitrary connection nesting, and I +wanted to implement that in Lisp (Propellor only supports something equivalent +to a single, unnested Lisp-type connection). Additionally, after five years +of using and extending Propellor, I've come to disagree with Joey about +whether Haskell's type system helps or hinders using and extending Propellor. + +.. Propellor_: https://propellor.branchable.com/ |