README 7.39 KB
Newer Older
Simon Josefsson's avatar
Add.    
Simon Josefsson committed
1
2
Cosmos - A simple Configuration Management System

Simon Josefsson's avatar
Fix.    
Simon Josefsson committed
3
   cosmos, noun, /ˈkɒzməs, -moʊs/ [koz-muhs, -mohs]
Simon Josefsson's avatar
Fix.    
Simon Josefsson committed
4

Simon Josefsson's avatar
Fix.    
Simon Josefsson committed
5
6
7
     1. the world or universe regarded as an orderly, harmonious system.
     2. a complete, orderly, harmonious system.
     3. order; harmony. 
Simon Josefsson's avatar
Add.    
Simon Josefsson committed
8
9

   κόσμος (genitive κόσμου) m, second declension; (kosmos)
Simon Josefsson's avatar
Update.    
Simon Josefsson committed
10

Simon Josefsson's avatar
Fix.    
Simon Josefsson committed
11
12
13
14
15
16
17
18
     1. order
     2. lawful order, government
     3. mode, fashion
     4. ornament, decoration
     5. honour, credit
     6. ruler
     7. world, universe, the earth
     8. mankind
Simon Josefsson's avatar
Add.    
Simon Josefsson committed
19

Simon Josefsson's avatar
Add.    
Simon Josefsson committed
20
21
22
Introduction
------------

Simon Josefsson's avatar
Simon Josefsson committed
23
24
25
26
27
28
29
30
31
32
Cosmos is a computer system administration tool that execute scripts
and install files on machines.  Typically it is used to manage a fleet
of server machines for an organisation.  Cosmos is designed in a
minimalistic way so that it easy to start to use without significant
changes to the machines, and it works well in parallel with other
system administration tools.  Cosmos requires a POSIX shell and rsync.

A version control system with a strong security model (e.g., git using
GnuPG to sign tags) is recommended for standard usage.  The version
controlled repository hold the Cosmos "model" for a set of machines.
Linus Nordberg's avatar
Linus Nordberg committed
33
The repository is usually centralized, and Cosmos helps you fetch and
Simon Josefsson's avatar
Simon Josefsson committed
34
35
verify the integrity and authenticity (using GnuPG) before using files
from it.
Simon Josefsson's avatar
Update.    
Simon Josefsson committed
36

Simon Josefsson's avatar
Fix.    
Simon Josefsson committed
37
38
Cosmos configuration lives in /etc/cosmos/ by default.  You may use
the environment variable COSMOS_CONF_DIR to specify a separate
Simon Josefsson's avatar
Update.    
Simon Josefsson committed
39
configuration directory.  The directory should contain the
Simon Josefsson's avatar
Fix.    
Simon Josefsson committed
40
configuration file cosmos.conf itself and the various *.d/
Simon Josefsson's avatar
Simon Josefsson committed
41
sub-directories which holds the extensible Cosmos implementation.  The
Simon Josefsson's avatar
Fix.    
Simon Josefsson committed
42
configuration file is read before parsing command line arguments.
Simon Josefsson's avatar
Update.    
Simon Josefsson committed
43

Simon Josefsson's avatar
Fix.    
Simon Josefsson committed
44
45
Using a version controlled repository is optional but recommended.
The repository is normally initialized by running 'cosmos clone VCURL'
46
47
to download a remote repository.  Currently 'https://' and 'git://'
URLs are supported.  For example:
Simon Josefsson's avatar
Update.    
Simon Josefsson committed
48

49
  cosmos clone https://git.example.org/git/your-cosmos.git
Simon Josefsson's avatar
Fix.    
Simon Josefsson committed
50

Simon Josefsson's avatar
Fix.    
Simon Josefsson committed
51
52
53
54
The default place for the Cosmos repository is /var/cache/cosmos/repo.
The path is specified in cosmos.conf by setting the COSMOS_REPO
environment variable.

Simon Josefsson's avatar
Update.    
Simon Josefsson committed
55
56
Normally you use the same repository for several machines, so you have
to specify the paths within the repository that should be used for the
Simon Josefsson's avatar
Fix.    
Simon Josefsson committed
57
machine you are configuring.  Set the environment variable
Simon Josefsson's avatar
Update.    
Simon Josefsson committed
58
59
60
61
COSMOS_REPO_MODELS in cosmos.conf to specify a list of colon separated
paths.  A list of paths is useful to aggregate scripts common to all
or a group of systems while preserving the ability to have a
per-server directory as well.
Simon Josefsson's avatar
Fix.    
Simon Josefsson committed
62

Simon Josefsson's avatar
Update.    
Simon Josefsson committed
63
64
65
For example, the machine "someserver.example.org" could use a path
where files for many systems are put, and a special path for that
system only.
Simon Josefsson's avatar
Fix.    
Simon Josefsson committed
66

Simon Josefsson's avatar
Update.    
Simon Josefsson committed
67
68
69
70
71
72
73
74
75
76
77
78
  COSMOS_REPO_MODELS="$COSMOS_REPO/someserver.example.org:$COSMOS_REPO/global"

When 'cosmos update' is invoked it will first update the repository
(e.g., 'git pull') and then recursively copy (using rsync) each of the
paths in COSMOS_REPO_MODELS into the path used by Cosmos to perform
its work, the Cosmos "model".

NOTE: If you have files named the same in multiple COSMOS_REPO_MODELS
directories, the file from the FIRST directory is the one that will be
copied to the target directory.  For the example above, files in the
"$COSMOS_REPO/someserver.example.org" directory takes precedence over
the "$COSMOS_REPO/global" directory.
Simon Josefsson's avatar
Fix.    
Simon Josefsson committed
79

Simon Josefsson's avatar
Fix.    
Simon Josefsson committed
80
The default place for the Cosmos "model" for your system is
Simon Josefsson's avatar
Update.    
Simon Josefsson committed
81
82
83
/var/cache/cosmos/model.  The path is specified in cosmos.conf by
setting the COSMOS_MODEL environment variable.  You may also override
it using the --root (or -r for short) on the command line.
Simon Josefsson's avatar
Fix.    
Simon Josefsson committed
84

Simon Josefsson's avatar
Fix.    
Simon Josefsson committed
85
86
87
It is below the COSMOS_MODEL path that you will find files that will
be applied to the machine.

Simon Josefsson's avatar
Fix.    
Simon Josefsson committed
88
89
To understand what Cosmos does, consider the following file system
tree structure:
Simon Josefsson's avatar
Fix.    
Simon Josefsson committed
90
91

   /etc/cosmos/cosmos.conf
Simon Josefsson's avatar
Update.    
Simon Josefsson committed
92
93
   /var/cache/cosmos/model/overlay/root/.ssh/foobar
   /var/cache/cosmos/model/delete/etc/somewhere/file-to-be-removed
Simon Josefsson's avatar
Fix.    
Simon Josefsson committed
94
95
96

The cosmos.conf file contains this:

Simon Josefsson's avatar
Update.    
Simon Josefsson committed
97
COSMOS_MODEL=/var/cache/cosmos/model
Simon Josefsson's avatar
Fix.    
Simon Josefsson committed
98
99
100
101
COSMOS_ROOT=/

The content of the two other files are irrelevant here.

Simon Josefsson's avatar
Update.    
Simon Josefsson committed
102
The /var/cache/cosmos/model/overlay/root/.ssh/foobar file holds a SSH
Simon Josefsson's avatar
Fix.    
Simon Josefsson committed
103
104
105
106
configuration file to be installed as /root/.ssh/foobar.  (The file
may more realistically be .authorized_keys, but I'm using a different
example filename to reduce the risk of accidental overwrites of that
critical file when you test configurations.)
Simon Josefsson's avatar
Fix.    
Simon Josefsson committed
107

Simon Josefsson's avatar
Update.    
Simon Josefsson committed
108
109
The /var/cache/cosmos/model/delete/etc/somewhere/file-to-be-removed is
a placeholder file to indicate that the file
Simon Josefsson's avatar
Fix.    
Simon Josefsson committed
110
111
112
113
114
115
116
117
118
119
/etc/somewhere/file-to-be-removed should be removed.  Below we'll
assume that you have a real file /etc/somewhere/file-to-be-removed on
your system that should be removed.

You can dry-run cosmos by using --dry-run (or -n for short).  In this
setup it would print the following.  It doesn't do anything!  No files
are removed and nothing is rsync'ed.

root@latte:~# cosmos -n apply
rm -f "/"/"./etc/somewhere/file-to-be-removed"
Simon Josefsson's avatar
Update.    
Simon Josefsson committed
120
rsync --archive /var/cache/cosmos/model/overlay/ /
Simon Josefsson's avatar
Fix.    
Simon Josefsson committed
121
122
root@latte:~# 

Simon Josefsson's avatar
Update.    
Simon Josefsson committed
123
124
125
126
This dry mode is not as useful as it could be, because you only see
that rsync will be invoked but not what it would do.  To run cosmos in
a semi-dry mode, which will invoke rsync in dry mode, there is the
--dry-tasks (or -N for short).
Simon Josefsson's avatar
Fix.    
Simon Josefsson committed
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143

root@latte:~# cosmos -N apply
rm -f "/"/"./etc/somewhere/file-to-be-removed"
sending incremental file list
root/.ssh/
root/.ssh/foobar

sent 89 bytes  received 20 bytes  218.00 bytes/sec
total size is 4  speedup is 0.04 (DRY RUN)
root@latte:~# 

If you think the output from the dry runs looks harmless, you can run
it for real.  Here the --verbose (or -v fort short) mode is enabled,
otherwise the command is silent.

root@latte:~# cosmos -v apply
40delete: Removing './etc/somewhere/file-to-be-removed'
Simon Josefsson's avatar
Update.    
Simon Josefsson committed
144
60overlay: Invoking rsync --archive -v /var/cache/cosmos/model/overlay/ /
Simon Josefsson's avatar
Fix.    
Simon Josefsson committed
145
146
147
148
149
150
151
152
153
sending incremental file list
root/.ssh/
root/.ssh/foobar

sent 133 bytes  received 36 bytes  338.00 bytes/sec
total size is 4  speedup is 0.02
root@latte:~# 

This illustrate the fundamental task that cosmos does.
Simon Josefsson's avatar
Add.    
Simon Josefsson committed
154

Simon Josefsson's avatar
Update.    
Simon Josefsson committed
155
156
Task scripts
------------
Simon Josefsson's avatar
Add.    
Simon Josefsson committed
157
158

All executable files in the pre-tasks.d and post-tasks.d sub-directory
Simon Josefsson's avatar
Update.    
Simon Josefsson committed
159
of the Cosmos model directory are invoked in order, sorted by 'sort'.
Simon Josefsson's avatar
Simon Josefsson committed
160
161
162
The scripts can do essentially anything, which is useful but can be
dangerous unless you are careful.  To write proper task scripts you
should consider the following guidelines.
Simon Josefsson's avatar
Add.    
Simon Josefsson committed
163

Simon Josefsson's avatar
Update.    
Simon Josefsson committed
164
* Write fast scripts!
Simon Josefsson's avatar
Add.    
Simon Josefsson committed
165
166
167

  The script may be invoked many times, sometimes frequently, and
  should finish quickly.  A simple way to achieve this is to wrap most
Simon Josefsson's avatar
Simon Josefsson committed
168
169
  of the commands on the script in a if-clause that checks for the
  existance of some stamp file.  Either like this:
Simon Josefsson's avatar
Add.    
Simon Josefsson committed
170

Simon Josefsson's avatar
Simon Josefsson committed
171
172
  if test -f /var/spool/cosmos/stamps/foobar.stamp; then
     apt-get install foobar
Simon Josefsson's avatar
Add.    
Simon Josefsson committed
173
     ...
Simon Josefsson's avatar
Simon Josefsson committed
174
175
     mkdir -p /var/spool/cosmos/stamps
     touch /var/spool/cosmos/stamps/foobar.stamp
Simon Josefsson's avatar
Add.    
Simon Josefsson committed
176
177
178
179
180
  fi

  Or without the need for a stamp file like this:

  if test -f /usr/bin/foobar; then
Simon Josefsson's avatar
Simon Josefsson committed
181
     apt-get install foobar
Simon Josefsson's avatar
Add.    
Simon Josefsson committed
182
  fi
Simon Josefsson's avatar
Fix.    
Simon Josefsson committed
183

Simon Josefsson's avatar
Fix.    
Simon Josefsson committed
184
185
186
187
188
189
190
191
* No interactive prompts

  The scripts may run unattended so they should not rely on having a
  user present.

  Exceptions may include some initial bootstrapping code if you make
  sure to always run those interactively and make sure that they are
  never invoked again.
Simon Josefsson's avatar
Simon Josefsson committed
192
193
194
195
196
197
198
199
200

* Respect the COSMOS_DRY_TASK environment variable

  This enable 'cosmos -N apply' to be more useful to the sysadmin, not
  having to 'sh -x' trace the task scripts.

* Use the COSMOS_VERBOSE environment variable when useful

  This enable 'cosmos -v apply' to produce interesting output.