You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
You can configure systems with OpenVox either in a client-server architecture, using the **OpenVox agent** and **OpenVox server** applications, or in a stand-alone architecture, using the **OpenVox apply** application.
19
+
You can configure systems with OpenVox either in a client-server architecture, using the
20
+
**OpenVox agent** and **OpenVox server** applications, or in a stand-alone architecture, using
21
+
the **OpenVox apply** application.
20
22
21
-
{:.concept}
22
23
## Catalogs
23
24
24
-
A catalog is a document that describes the desired system state for one specific computer. It lists all of the resources that need to be managed, as well as any dependencies between those resources.
25
+
A catalog is a document that describes the desired system state for one specific computer. It
26
+
lists all of the resources that need to be managed, as well as any dependencies between those
27
+
resources.
25
28
26
29
OpenVox configures systems in two stages:
27
30
28
31
1. Compile a catalog.
29
32
2. Apply the catalog.
30
33
31
-
To compile a catalog, OpenVox uses several sources of information. For more info, see the pages on [basics of the OpenVox language][lang_basics] and [catalog compilation][catalog_compilation].
34
+
To compile a catalog, OpenVox uses several sources of information. For more info, see the pages
35
+
on [basics of the OpenVox language][lang_basics] and [catalog compilation][catalog_compilation].
32
36
33
-
{:.concept}
34
37
## The agent-server architecture
35
38
36
-
When set up as an agent-server architecture, an OpenVox server controls the configuration information, and each managed agent node requests its own configuration catalog from the server.
39
+
When set up as an agent-server architecture, an OpenVox server controls the configuration
40
+
information, and each managed agent node requests its own configuration catalog from the server.
37
41
38
-
In this architecture, managed nodes run the **OpenVox agent** application, usually as a background or scheduled service. One or more servers run the **OpenVox server** application, [OpenVox Server][].
42
+
In this architecture, managed nodes run the **OpenVox agent** application, usually as a
43
+
background or scheduled service. One or more servers run the **OpenVox server** application,
44
+
[OpenVox Server][].
39
45
40
-
Periodically, each OpenVox agent sends facts to the OpenVox server, and requests a catalog. The server compiles and returns that node's catalog, using several sources of information it has access to.
46
+
Periodically, each OpenVox agent sends facts to the OpenVox server, and requests a catalog. The
47
+
server compiles and returns that node's catalog, using several sources of information it has
48
+
access to.
41
49
42
-
Once it receives a catalog, OpenVox agent applies it to the node by checking each [resource][] the catalog describes. If it finds any resources that are not in their desired state, it makes the changes necessary to correct them. Or, in no-op mode, it reports on what changes would have been done.
50
+
Once it receives a catalog, OpenVox agent applies it to the node by checking each [resource][]
51
+
the catalog describes. If it finds any resources that are not in their desired state, it makes
52
+
the changes necessary to correct them. Or, in no-op mode, it reports on what changes would have
53
+
been done.
43
54
44
55
After applying the catalog, the agent sends a report to the OpenVox server.
45
56
@@ -49,16 +60,22 @@ For more information, see:
49
60
*[OpenVox Agent on Windows Systems][agent_win]
50
61
*[OpenVox Server][]
51
62
52
-
{:.section}
53
63
### Communications and security
54
64
55
65
OpenVox agent nodes and OpenVox servers communicate by HTTPS with client SSL verification.
56
66
57
-
The OpenVox Server provides an HTTP interface, with [various endpoints][server_http] available. When requesting or submitting anything to the server, the agent makes an HTTPS request to one of those endpoints.
67
+
The OpenVox Server provides an HTTP interface, with [various endpoints][server_http] available.
68
+
When requesting or submitting anything to the server, the agent makes an HTTPS request to one
69
+
of those endpoints.
58
70
59
-
Client-verified HTTPS means each server or agent must have an identifying SSL certificate. They each examine their counterpart's certificate to decide whether to allow an exchange of information.
71
+
Client-verified HTTPS means each server or agent must have an identifying SSL certificate. They
72
+
each examine their counterpart's certificate to decide whether to allow an exchange of
73
+
information.
60
74
61
-
OpenVox includes a built-in certificate authority for managing certificates. Agents can automatically request certificates through the server's HTTP API. You can use the **puppet ssl** command on an agent to inspect local certificates. The **puppetserver ca** command on the server manages new and existing certificates. Agents can then download the signed certificates.
75
+
OpenVox includes a built-in certificate authority for managing certificates. Agents can
76
+
automatically request certificates through the server's HTTP API. You can use the **puppet ssl**
77
+
command on an agent to inspect local certificates. The **puppetserver ca** command on the server
78
+
manages new and existing certificates. Agents can then download the signed certificates.
62
79
63
80
For more information, see:
64
81
@@ -67,32 +84,64 @@ For more information, see:
67
84
*[The OpenVox server's auth.conf file][auth.conf]
68
85
*[Background reference on SSL and HTTPS.](/docs/background/ssl/)
69
86
70
-
{:.concept}
71
87
## The stand-alone architecture
72
88
73
-
Alternatively, OpenVox can run in a stand-alone architecture, where each managed node has its own complete copy of your configuration info and compiles its own catalog.
89
+
Alternatively, OpenVox can run in a stand-alone architecture, where each managed node has its
90
+
own complete copy of your configuration info and compiles its own catalog.
74
91
75
-
In this architecture, managed nodes run the **OpenVox apply** application, usually as a scheduled task or cron job. You can also run it on demand for initial configuration of a server or for smaller configuration tasks.
92
+
In this architecture, managed nodes run the **OpenVox apply** application, usually as a
93
+
scheduled task or cron job. You can also run it on demand for initial configuration of a server
94
+
or for smaller configuration tasks.
76
95
77
-
Like the OpenVox server application, OpenVox apply needs access to several sources of configuration data, which it uses to compile a catalog for the node it is managing.
96
+
Like the OpenVox server application, OpenVox apply needs access to several sources of
97
+
configuration data, which it uses to compile a catalog for the node it is managing.
78
98
79
-
After OpenVox apply compiles the catalog, it immediately applies it by checking each [resource][] the catalog describes. If it finds any resources that are not in their desired state, it makes the changes necessary to correct them. Or, in no-op mode, it reports on what changes would have been needed.
99
+
After OpenVox apply compiles the catalog, it immediately applies it by checking each [resource][]
100
+
the catalog describes. If it finds any resources that are not in their desired state, it makes
101
+
the changes necessary to correct them. Or, in no-op mode, it reports on what changes would have
102
+
been needed.
80
103
81
-
After applying the catalog, OpenVox apply stores a report on disk. You can configure it to send reports to a central service.
104
+
After applying the catalog, OpenVox apply stores a report on disk. You can configure it to send
105
+
reports to a central service.
82
106
83
107
For more information, see the documentation for [the OpenVox apply application][apply].
84
108
85
-
{:.concept}
86
109
## Differences between agent-server and stand-alone
87
110
88
-
In general, OpenVox apply can do the same things as the combination of OpenVox agent and OpenVox server, but there are several trade-offs around security and the ease of certain tasks.
89
-
90
-
If you don't have a preference, you should select the agent-server architecture. If you have questions, considering these trade-offs helps you make your decision.
91
-
92
-
***Principle of least privilege.** In agent-server OpenVox, each agent only gets its own configuration, and is unable to see how other nodes are configured. With OpenVox apply, it's impractical to do this, so every node has access to complete knowledge about how your site is configured. Depending on how you're configuring your systems, this can potentially raise the risks of horizontal privilege escalation.
93
-
***Ease of centralized reporting and inventory.** Agents send reports to the OpenVox server by default, and the server can be configured with any number of [report handlers][] to pass these on to other services. You can also connect the master to [OpenVoxDB][], a powerful tool for querying inventory and activity data. OpenVox apply nodes handle their own information, so if you're using OpenVoxDB or sending reports to another service, _each_ node needs to be configured and authorized to connect to it.
94
-
***Ease of updating configurations.** Only OpenVox servers have the Puppet modules, main manifests, and other data necessary for compiling catalogs. This means that when you need to update your systems' configurations, you only need to update content on one (or a few) OpenVox servers. In a decentralized `puppet apply` deployment, you'll need to sync new configuration code and data to every node.
95
-
***CPU and memory usage on managed machines.** Since OpenVox agent doesn't compile its own catalogs, it uses fewer resources on the machines it manages, leaving them with more capacity for their designated tasks.
96
-
***Need for a dedicated OpenVox server.** The OpenVox server takes on the performance load of compiling all catalogs, and it should usually be a dedicated machine with a fast processor, lots of RAM, and a fast disk. Not everybody wants to (or is able to) allocate that, and OpenVox apply can get around the need for it.
97
-
***Need for good network connectivity.** Agents need to be able to reach the OpenVox server at a reliable hostname in order to configure themselves. If a system lives in a degraded or isolated network environment, you might want it to be more self-sufficient.
98
-
***Security overhead.** Agents and servers use HTTPS to secure their communications and authenticate each other, and every system involved needs an SSL certificate. OpenVox includes a built-in CA to easily manage certificates, but it's even easier to not manage them at all. (Of course, you'll still need to manage security somehow, since you're probably using Rsync or something to update OpenVox content on every node.)
111
+
In general, OpenVox apply can do the same things as the combination of OpenVox agent and OpenVox
112
+
server, but there are several trade-offs around security and the ease of certain tasks.
113
+
114
+
If you don't have a preference, you should select the agent-server architecture. If you have
115
+
questions, considering these trade-offs helps you make your decision.
116
+
117
+
***Principle of least privilege.** In agent-server OpenVox, each agent only gets its own
118
+
configuration, and is unable to see how other nodes are configured. With OpenVox apply, it's
119
+
impractical to do this, so every node has access to complete knowledge about how your site is
120
+
configured. Depending on how you're configuring your systems, this can potentially raise the
121
+
risks of horizontal privilege escalation.
122
+
***Ease of centralized reporting and inventory.** Agents send reports to the OpenVox server by
123
+
default, and the server can be configured with any number of [report handlers][] to pass these
124
+
on to other services. You can also connect the server to [OpenVoxDB][], a powerful tool for
125
+
querying inventory and activity data. OpenVox apply nodes handle their own information, so if
126
+
you're using [OpenVoxDB][] or sending reports to another service, _each_ node needs to be
127
+
configured and authorized to connect to it.
128
+
***Ease of updating configurations.** Only OpenVox servers have the Puppet modules, main
129
+
manifests, and other data necessary for compiling catalogs. This means that when you need to
130
+
update your systems' configurations, you only need to update content on one (or a few) OpenVox
131
+
servers. In a decentralized `puppet apply` deployment, you'll need to sync new configuration
132
+
code and data to every node.
133
+
***CPU and memory usage on managed machines.** Since OpenVox agent doesn't compile its own
134
+
catalogs, it uses fewer resources on the machines it manages, leaving them with more capacity
135
+
for their designated tasks.
136
+
***Need for a dedicated OpenVox server.** The OpenVox server takes on the performance load of
137
+
compiling all catalogs, and it should usually be a dedicated machine with a fast processor,
138
+
lots of RAM, and a fast disk. Not everybody wants to (or is able to) allocate that, and OpenVox
139
+
apply can get around the need for it.
140
+
***Need for good network connectivity.** Agents need to be able to reach the OpenVox server at
141
+
a reliable hostname in order to configure themselves. If a system lives in a degraded or
142
+
isolated network environment, you might want it to be more self-sufficient.
143
+
***Security overhead.** Agents and servers use HTTPS to secure their communications and
144
+
authenticate each other, and every system involved needs an SSL certificate. OpenVox includes a
145
+
built-in CA to easily manage certificates, but it's even easier to not manage them at all. (Of
146
+
course, you'll still need to manage security somehow, since you're probably using Rsync or
147
+
something to update OpenVox content on every node.)
0 commit comments