-
Notifications
You must be signed in to change notification settings - Fork 2
/
Copy pathexample.html
120 lines (116 loc) · 5.79 KB
/
example.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>Example - Holo</title>
<link rel="stylesheet" type="text/css" href="/site.css">
</head>
<body>
<header>
<div id="header-buttons">
<a href="https://twitter.com/holocm" title="Follow on Twitter"><span class="logo logo-twitter"></span></a>
<a href="https://github.com/holocm" title="Fork on GitHub"><span class="logo logo-github"></span></a>
</div>
<div id="small-logo">
<a href="/index.html"><img src="/img/holo-logo.svg"></a>
</div>
</header>
<nav>
<ul>
<li><a href="/example.html" class="self-link">Example</a></li>
<li><a href="/man/holo.8.html" class="">Docs</a></li>
<li><a href="/install.html" class="">Installation</a></li>
</ul>
</nav>
<section><h1>How does Holo configure systems?</h1>
<p>Holo users ship configuration in packages, usually called "holograms". These can be built with the regular package
building tools (debuild, rpmbuild, makepkg, etc.) or with Holo's own <a href="https://github.com/holocm/holo-build">holo-build</a>
tool that offers a much more pleasant syntax and process. Let's go through an example hologram that installs and starts
an OpenSSH server and tweaks some of its configuration.</p>
<h2>The package declaration</h2>
<p>Package declarations for holo-build are <a href="https://github.com/toml-lang/toml">TOML files</a>.</p>
<pre><code class="language-toml">[package]
name = "hologram-openssh"
version = "1.0.0"
description = "Start and configure OpenSSH"
requires = ["openssh"]
</code></pre>
<p>Packages can install files, directories and symlinks. For example, we may want to start SSH only after the firewall is
set up, so we create a configuration file for systemd.</p>
<pre><code class="language-toml">[[file]]
path = "/etc/systemd/system/sshd.service.d/hardened.conf"
content = """
[Unit]
After=firewall.service
"""
</code></pre>
<p>We also want to disable password authentication. This one is a bit more tricky: We want to modify the configuration
installed by the OpenSSH package, but the configuration is also a package, so it may not install the same file path.
Instead, we install a script that Holo will later find and execute to update the default configuration.</p>
<pre><code class="language-toml">[[file]]
path = "/usr/share/holo/files/10-openssh/etc/ssh/sshd_config.holoscript"
mode = "0755"
content = """
#!/bin/sh
# stdin has the default config and stdout wants the updated config;
# we just add a line at the bottom
cat
echo "PasswordAuthentication no"
"""
</code></pre>
<p>Any file below <code>/usr/share/holo</code> will imply a dependency on the <code>holo</code> package and have <code>holo apply</code> run
automatically when the package is installed or removed.</p>
<p>When everything is set up, we start the daemon:</p>
<pre><code class="language-toml">[[action]]
on = "setup"
script = """
systemctl daemon-reload
systemctl enable sshd
systemctl restart sshd
"""
</code></pre>
<h2>Rolling it out</h2>
<p>Once the package declaration is complete, a system package (.deb, .rpm, etc.) can be produced by
<a href="https://github.com/holocm/holo-build">holo-build</a>. No extra tools needed.</p>
<pre><code>$ holo-build --debian hologram-openssh.pkg.toml
</code></pre>
<p>Since we had files below <code>/usr/share/holo</code>, Holo will be installed as a dependency and <code>holo apply</code> will be executed
during installation:</p>
<pre><code># dpkg -i hologram-openssh_1.0.0-1_any.deb
...
Working on file:/etc/ssh/sshd_config
store at /var/lib/holo/files/base/etc/ssh/sshd_config
passthru /usr/share/holo/files/10-openssh/etc/ssh/sshd_config.holoscript
...
</code></pre>
<p>This tells us that the default configuration has been modified as described by our holoscript. And indeed:</p>
<pre><code>$ tail -n1 /etc/ssh/sshd_config
PasswordAuthentication no
</code></pre>
<h2>Monitoring for changes</h2>
<p>When Holo provisions an entity (such as this config file), it will always store a <strong>base image</strong> describing the original
state of the entity. If the entity is changed afterwards, Holo will be able to detect this change:</p>
<pre><code># sed -i '/PasswordAuthentication/ s/no/yes/' /etc/ssh/sshd_config
# holo apply
Working on file:/etc/ssh/sshd_config
store at /var/lib/holo/files/base/etc/ssh/sshd_config
passthru /usr/share/holo/files/10-openssh/etc/ssh/sshd_config.holoscript
!! Entity has been modified by user (use --force to overwrite)
diff --holo /var/lib/holo/files/provisioned/etc/ssh/sshd_config /etc/ssh/sshd_config
--- /etc/ssh/sshd_config
+++ /etc/ssh/sshd_config
@@ -131,3 +131,3 @@
# ForceCommand cvs server
-PasswordAuthentication no
+PasswordAuthentication yes
</code></pre>
<h2>But wait, there's more!</h2>
<p>With <strong>plugins</strong>, Holo can be taught to provision other things than files. For example, there are plugins for
<a href="https://github.com/holocm/holo-users-groups">user accounts, groups</a> or
<a href="https://github.com/holocm/holo-ssh-keys">SSH public keys</a>. You can easily write your own plugins; they can be as small
as <a href="https://github.com/holocm/holo/blob/master/cmd/holo-run-scripts">one shell script</a>.</p>
<p>This example has demonstrated the holo-files plugin that ships with Holo itself, but it can only scratch the surface.
Check out the <a href="./man/holo.8.html">man pages</a> for the full documentation. And
don't forget to <a href="./install.html">install Holo</a> on your system, too.</section>
</body>