Skip to content

Commit 959592f

Browse files
miharpclaude
miharp
and
claude
committed
Modernize OpenVox 8 install and upgrade documentation
- Rewrite install/upgrade pages around current OpenVox package names and repo URLs, aligned with voxpupuli.org/openvox/install/ - Delete historical Puppet 3→5 major upgrade pages and remove their nav entries - Consolidate whered_it_go into install_what_and_where to eliminate duplicate file layout content - Fix stale puppet cert commands replaced by puppetserver ca in Puppet 6 - Restore openvox-agent component version table in about_agent.md - Add cross-link to OpenVox Server docs in install_pre Signed-off-by: Michael Harp <mike@mikeharp.com> Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
1 parent 25e7efa commit 959592f

16 files changed

Lines changed: 341 additions & 1588 deletions

‎_data/nav/openvox_8x.yml‎

Lines changed: 8 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,7 @@
77
link: "known_issues.html"
88
- text: System requirements
99
link: "system_requirements.html"
10-
- text: Component versions in `openvox-agent`
10+
- text: About `openvox-agent`
1111
link: "about_agent.html"
1212
- text: Quick start guides
1313
items:
@@ -37,9 +37,9 @@
3737
items:
3838
- text: Overview of OpenVox's architecture
3939
link: "architecture.html"
40-
- text: Pre-install tasks
40+
- text: Before you begin
4141
link: "install_pre.html"
42-
- text: OpenVox Platform repositories
42+
- text: OpenVox repositories and packages
4343
link: "openvox_platform.html"
4444
- text: 'Install agent: Linux'
4545
link: "install_linux.html"
@@ -49,17 +49,7 @@
4949
link: "install_osx.html"
5050
- text: What gets installed and where (agent)
5151
link: "install_what_and_where.html"
52-
- text: File location changes since OpenVox 3.8.x
53-
link: "whered_it_go.html"
54-
- text: Pre-upgrade tasks from 3.8
55-
link: "upgrade_major_pre.html"
56-
- text: Upgrade agents from 3.8.x OpenVox 5.x
57-
link: "upgrade_major_agent.html"
58-
- text: Upgrade servers
59-
link: "upgrade_major_server.html"
60-
- text: Post-upgrade cleanup
61-
link: "upgrade_major_post.html"
62-
- text: 'Minor upgrades: From OpenVox 4 and within OpenVox 5.x'
52+
- text: Upgrading OpenVox 8
6353
link: "upgrade_minor.html"
6454
- text: Configuration
6555
items:
@@ -145,11 +135,11 @@
145135
link: "services_commands.html"
146136
- text: Running OpenVox commands on Windows
147137
link: "services_commands_windows.html"
148-
- text: The rack OpenVox master
138+
- text: The rack OpenVox server
149139
link: "services_master_rack.html"
150140
- text: Configuring a Server with Passenger and Apache
151141
link: "passenger.html"
152-
- text: The WEBrick OpenVox master
142+
- text: The WEBrick OpenVox server
153143
link: "services_master_webrick.html"
154144
- text: OpenVox agent on *nix
155145
link: "services_agent_unix.html"
@@ -453,7 +443,7 @@
453443
link: "man/apply.html"
454444
- text: puppet cert
455445
link: "man/cert.html"
456-
- text: puppet master
446+
- text: legacy server command
457447
link: "man/master.html"
458448
- text: puppet module
459449
link: "man/module.html"
@@ -565,7 +555,7 @@
565555
link: "ssl_regenerate_certificates.html"
566556
- text: Details about OpenVox's internals
567557
items:
568-
- text: Agent/master HTTPS communications
558+
- text: Agent/server HTTPS communications
569559
link: "subsystem_agent_master_comm.html"
570560
- text: Catalog compilation
571561
link: "subsystem_catalog_compilation.html"

‎docs/_openvox_8x/_puppet_toc.html‎

Lines changed: 0 additions & 385 deletions
This file was deleted.

‎docs/_openvox_8x/about_agent.md‎

Lines changed: 39 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -1,41 +1,55 @@
11
---
22
layout: default
3-
title: "Component versions in OpenVox-agent"
3+
title: "About `openvox-agent`"
44
---
55

6-
[OpenFact]: /openfact/latest/
7-
[Hiera]: ./hiera_intro.html
8-
[agent]: ./services_agent_unix.html
9-
[apply]: ./services_apply.html
10-
[OpenVox Server]: /openvox-server/latest/
11-
[release notes]: ./release_notes.html
6+
[release_notes]: ./release_notes.html
7+
[services_agent]: ./services_agent_unix.html
8+
[services_apply]: ./services_apply.html
9+
[openvox_server]: /openvox-server/latest/
1210

13-
## Release contents of `OpenVox-agent` 8.x
11+
`openvox-agent` is the core OpenVox package for managed nodes and standalone use.
12+
It bundles the OpenVox runtime and the dependencies needed to run it, so it is the
13+
package you install on Linux, macOS, and Windows agent nodes.
1414

15-
See the table for details about which components shipped in which `openvox-agent` release, and the [package-specific release notes][release notes] for more information about packaging and installation fixes and features.
15+
## What `openvox-agent` provides
1616

17-
| OpenVox release | OpenFact | Ruby | OpenSSL |
18-
|-----------------|----------|--------|---------|
19-
| 8.26.2 | 5.6.0 | 3.2.11 | 3.0.20 |
20-
| 8.26.1 | 5.6.0 | 3.2.11 | 3.0.20 |
21-
| 8.26.0 | 5.6.0 | 3.2.11 | 3.0.20 |
22-
| 8.25.0 | 5.4.0 | 3.2.10 | 3.0.19 |
17+
The package includes:
2318

24-
## What `openvox-agent` and OpenVox Server are
19+
- the `puppet` and `facter` commands
20+
- the OpenVox agent service
21+
- the runtime needed for `puppet apply`
22+
- bundled dependencies such as Ruby and OpenSSL
2523

26-
We distribute OpenVox as two core packages.
24+
After installation, you can run the [OpenVox agent service][services_agent] or use
25+
[standalone apply workflows][services_apply] on the same host.
2726

28-
- `openvox-agent` --- This package contains OpenVox's main code and all of the dependencies needed to run it, including [OpenFact][], [Hiera][], and bundled versions of Ruby and OpenSSL. Once it's installed, you have everything you need to run [the OpenVox agent service][agent] and the [`puppet apply` command][apply].
29-
- `openvox-server` --- This package depends on `openvox-agent`, and adds the JVM-based [OpenVox Server][] application. Once it's installed, OpenVox Server can serve catalogs to nodes running the OpenVox agent service.
27+
## Relationship to other packages
3028

31-
## How version numbers work
29+
OpenVox is usually installed as a small set of packages:
3230

33-
OpenVox Server is a separate application that, among other things, runs instances of the OpenVox server application. It has its own version number separate from the version of OpenVox it runs and may be compatible with more than one existing OpenVox version.
31+
- `openvox-agent` for agent nodes and standalone use
32+
- `openvox-server` for catalog compilation and CA services on server nodes
33+
- `openvoxdb` for exported resources, reports, and inventory data
34+
- `openvoxdb-termini` on server nodes that need to talk to OpenVoxDB
3435

35-
The `openvox-agent` package also has its own version number, which doesn't necessarily match the version of OpenVox it installs.
36+
`openvox-server` depends on `openvox-agent`, so server upgrades often pull in a
37+
newer `openvox-agent` package on the server at the same time.
3638

37-
Order is important in the upgrade process. First, update OpenVox Server, then you update `openvox-agent`. If you upgrade OpenVox Server or OpenVoxDB to version 8, if you're on the master it will automatically upgrade the `openvox-agent` package to OpenVox agent 8.0.0 or newer. OpenVox Server 8 will also prevent you from installing anything lower than `openvox-agent` 8.0.0 on your agent nodes.
39+
## Versions and release notes
3840

39-
Since the `openvox-agent` package distributes several different pieces of software, its version number will frequently increase when OpenVox's version does not --- for example, `openvox-agent` 8.25.0 shipped the same OpenVox version but different Facter versions. Similarly, new versions of OpenVox Server usually don't require updates to the core OpenVox code.
41+
The `openvox-agent` package version is a package release number, not a separate
42+
product line. It can change when bundled dependencies or packaging details change,
43+
even if the core OpenVox language and command behavior stay the same.
4044

41-
This versioning scheme helps us avoid a bunch of "empty" OpenVox releases where the version number increases without any changes to OpenVox itself.
45+
For package-specific changes, see the [OpenVox release notes][release_notes] and the
46+
latest [OpenVox Server documentation][openvox_server].
47+
48+
## Release contents of `openvox-agent` 8.x
49+
50+
| OpenVox release | OpenFact | Ruby | OpenSSL |
51+
| --- | --- | --- | --- |
52+
| 8.26.2 | 5.6.0 | 3.2.11 | 3.0.20 |
53+
| 8.26.1 | 5.6.0 | 3.2.11 | 3.0.20 |
54+
| 8.26.0 | 5.6.0 | 3.2.11 | 3.0.20 |
55+
| 8.25.0 | 5.4.0 | 3.2.10 | 3.0.19 |

‎docs/_openvox_8x/install_linux.markdown‎

Lines changed: 46 additions & 34 deletions
Original file line numberDiff line numberDiff line change
@@ -1,58 +1,70 @@
11
---
22
layout: default
3-
title: "Installing Puppet agent: Linux"
3+
title: "Installing OpenVox agent: Linux"
44
---
55

6-
[master_settings]: ./config_important_settings.html#settings-for-puppet-master-servers
76
[agent_settings]: ./config_important_settings.html#settings-for-agents-all-nodes
8-
[where]: ./whered_it_go.html
9-
[dns_alt_names]: /puppet/latest/configuration.html#dnsaltnames
10-
[server_heap]: {{puppetserver}}/install_from_packages.html#memory-allocation
11-
[puppetserver_confd]: {{puppetserver}}/configuration.html
12-
[server_install]: {{puppetserver}}/install_from_packages.html
13-
[modules]: ./modules_fundamentals.html
14-
[main manifest]: ./dirs_manifest.html
15-
[environments]: ./environments.html
16-
[`puppet-agent`]: ./about_agent.html
177

18-
Install the Puppet agent so that your master can communicate with your Linux nodes.
8+
Install `openvox-agent` on Linux nodes that will run the OpenVox agent service or
9+
use `puppet apply`.
1910

20-
**Before you begin**: Review the [pre-install tasks](./install_pre.html) and [installing Puppet Server][server_install].
11+
**Before you begin:** Review the [pre-install tasks](./install_pre.html). If this
12+
node will connect to an OpenVox Server, make sure the server side is already installed
13+
and reachable.
2114

22-
1. Install a release package to [enable Puppet Platform repositories](./puppet_platform.html).
15+
1. Enable the OpenVox repository for your distribution.
2316

24-
2. Confirm that you can run Puppet executables.
17+
Follow the repository guidance on [OpenVox repositories and packages](./openvox_platform.html)
18+
or the published [Installing OpenVox](https://voxpupuli.org/openvox/install/) page.
2519

26-
The location for Puppet's executables is `/opt/puppetlabs/bin/`, which is not in your `PATH` environment variable by default.
20+
2. Install the package.
2721

28-
The executable path doesn't matter for Puppet services --- for instance, `service puppet start` works regardless of the `PATH` --- but if you're running interactive `puppet` commands, you must either add their location to your `PATH` or execute them using their full path.
22+
On apt-based systems:
2923

30-
To quickly add the executable location to your `PATH` for your current terminal session, use the command `export PATH=/opt/puppetlabs/bin:$PATH`. You can also add this location wherever you configure your `PATH`, such as your `.profile` or `.bashrc` configuration files.
24+
```bash
25+
sudo apt update
26+
sudo apt install openvox-agent
27+
```
3128

32-
For more information, see details about [file and directory locations][where].
29+
On yum-based systems:
3330

34-
4. Install the `puppet-agent` package on your Puppet agent nodes using the command appropriate to your system:
31+
```bash
32+
sudo yum install openvox-agent
33+
```
3534

36-
* Yum -- `sudo yum install puppet-agent`
37-
* Apt -- `sudo apt-get install puppet-agent`
38-
* Zypper -- `sudo zypper install puppet-agent`
35+
3. Confirm that you can run the OpenVox executables.
3936

40-
5. (Optional) Configure agent settings.
37+
The public binaries are installed under `/opt/puppetlabs/bin`. Add that directory
38+
to your `PATH` for interactive use, or call the binaries with their full path.
4139

42-
For example, if your master isn't reachable at the default address, `server = puppet`, set the `server` setting to your Puppet master's hostname.
40+
```bash
41+
export PATH=/opt/puppetlabs/bin:$PATH
42+
```
4343

44-
For other settings you might want to change, see a [list of agent-related settings][agent_settings].
44+
4. Configure agent settings if needed.
4545

46-
6. Start the `puppet` service: `sudo /opt/puppetlabs/bin/puppet resource service puppet ensure=running enable=true`.
46+
If the server is not reachable as `puppet`, set the `server` value in
47+
`puppet.conf`. For other commonly adjusted settings, see the
48+
[agent settings list][agent_settings].
4749

48-
7. (Optional) To see a sample of Puppet agent's output and verify any changes you may have made to your configuration settings in step 5, manually launch and watch a Puppet run:
49-
`sudo /opt/puppetlabs/bin/puppet agent --test`
50+
5. Start and enable the agent service.
5051

51-
8. Sign certificates on the certificate authority (CA) master.
52+
```bash
53+
sudo /opt/puppetlabs/bin/puppet resource service puppet ensure=running enable=true
54+
```
5255

53-
On the Puppet master:
56+
6. Run a test check-in.
5457

55-
1. Run `sudo /opt/puppetlabs/bin/puppet cert list` to see any outstanding requests.
56-
2. Run `sudo /opt/puppetlabs/bin/puppet cert sign <NAME>` to sign a request.
58+
```bash
59+
sudo /opt/puppetlabs/bin/puppet agent --test
60+
```
5761

58-
As each Puppet agent runs for the first time, it submits a certificate signing request (CSR) to the CA Puppet master. You must log into that server to check for and sign certificates. After an agent's certificate is signed, it regularly fetches and applies configuration catalogs from the Puppet master.
62+
7. Sign the node certificate on the CA, if your deployment requires manual signing.
63+
64+
```bash
65+
sudo /opt/puppetlabs/bin/puppetserver ca list
66+
sudo /opt/puppetlabs/bin/puppetserver ca sign --certname <NAME>
67+
```
68+
69+
If you are replacing Puppet packages on an existing host, back up `/etc/puppetlabs/`
70+
before you begin. OpenVox continues to use that configuration tree after installation.

0 commit comments

Comments
 (0)