Skip to content

Commit 14d5743

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 Signed-off-by: Michael Harp <mike@mikeharp.com> Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
1 parent 25402ae commit 14d5743

16 files changed

Lines changed: 330 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: 30 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -1,41 +1,46 @@
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].

‎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.

‎docs/_openvox_8x/install_osx.md‎

Lines changed: 39 additions & 77 deletions
Original file line numberDiff line numberDiff line change
@@ -1,104 +1,66 @@
11
---
22
layout: default
3-
title: "Installing Puppet agent: macOS"
3+
title: "Installing OpenVox agent: macOS"
44
---
55

6-
[server_install]: {{puppetserver}}/install_from_packages.html
7-
[where]: ./whered_it_go.html
86
[agent_settings]: ./config_important_settings.html#settings-for-agents-all-nodes
97

10-
These instructions cover installing Puppet agent on macOS machines.
8+
These instructions cover installing `openvox-agent` on macOS systems.
119

12-
1. Before installing Puppet agent, read the [pre-install tasks](./install_pre.html) and [install Puppet Server][server_install].
10+
1. Before installing `openvox-agent`, read the [pre-install tasks](./install_pre.html).
1311

14-
> **Note:** If you've used older Puppet versions, Puppet 4 changed the locations for a lot of the most important files and directories. [See this page for a summary of the changes.][where]
12+
2. Download the current macOS package from
13+
<https://downloads.voxpupuli.org/mac>.
1514

16-
2. Download the macOS [`puppet-agent` package](https://downloads.puppetlabs.com/mac/) specific to your version of macOS.
15+
The macOS package bundles the runtime it needs, so you do not need to install
16+
Ruby or other OpenVox dependencies separately.
1717

18-
The `puppet-agent` package bundles all of Puppet's prerequisites, so you don't need to download anything else to install Puppet on an agent node.
18+
3. Install the package.
1919

20-
OS X packages are named according to their `puppet-agent` version and compatible OS X version:
20+
You can use the graphical installer or install from the command line.
2121

22-
`puppet-agent-<PACKAGE VERSION>.osx<OS X VERSION>.dmg`
22+
## Graphical installation
2323

24-
For example:
24+
1. Open the downloaded disk image.
25+
2. Run the included installer package.
26+
3. Follow the prompts to complete the installation.
2527

26-
`puppet-agent-1.3.2.osx10.11.dmg`
28+
## Command-line installation
2729

28-
Note that the filename uses "osx" on newer versions of the operating system, which are called macOS.
30+
1. Mount the disk image:
2931

30-
To see which versions of Puppet and its related tools and components are in a given `puppet-agent` release, as well as release notes for each release, [see About Puppet agent](./about_agent.html).
32+
```bash
33+
sudo hdiutil mount <DMG FILE>
34+
```
3135

32-
> **Previous package names**
33-
>
34-
> We used some different naming schemes in the puppet-agent 1.2 series before settling on the current convention established in 1.2.5.
35-
>
36-
> - 1.2.0 through 1.2.2: `puppet-agent-<VERSION>-osx-<OS X VERSION>-<ARCH>.dmg`. Redundant; OS X only runs on x86_64.
37-
> - 1.2.4: `puppet-agent-<VERSION>-<OS X CODE NAME>.dmg`. This was too hard for automated tooling to deal with, because OS X's built-in CLI tools don't report the code name.
36+
2. Install the package from the mounted image:
3837

39-
3. Make sure you can run Puppet executables.
38+
```bash
39+
sudo installer -pkg /Volumes/<IMAGE>/<PKG FILE> -target /
40+
```
4041

41-
Puppet's executables are located in `/opt/puppetlabs/bin/`, which is not in your `PATH` environment variable by default.
42+
3. Unmount the disk image when you are done:
4243

43-
This doesn't matter for Puppet services, so enabling or disabling Puppet agent with `launchctl` works fine. However, if you're running any interactive `puppet` commands, you need to either add the location to your `PATH` or refer to the executables by their full locations.
44+
```bash
45+
sudo hdiutil unmount /Volumes/<IMAGE>
46+
```
4447

45-
> **Note:** If upgrading from Puppet 3, see [our page about which files and directories moved in Puppet 4 and later][where].
48+
## After installation
4649

47-
4. Install Puppet.
50+
1. Add `/opt/puppetlabs/bin` to your `PATH` if you want to run `puppet` and
51+
`facter` without the full path.
4852

49-
There are three ways to install Puppet on OS X:
53+
2. Configure the server name in `puppet.conf` if your server is not reachable
54+
as `puppet`. For commonly changed settings, see the
55+
[agent settings list][agent_settings].
5056

51-
- With the GUI installer.
52-
- On the command line.
53-
- With Puppet (if upgrading).
57+
3. Run a test agent execution if this node will talk to an OpenVox Server:
5458

55-
Regardless which you choose, installing the package will start the `puppet` and `mcollective` services. You can later disable these services with `launchctl` or with `sudo puppet resource service <NAME> ensure=stopped enable=false`.
59+
```bash
60+
sudo /opt/puppetlabs/bin/puppet agent --test
61+
```
5662

57-
5. Configure critical agent settings.
63+
4. Sign the certificate on the CA if your deployment uses manual certificate approval.
5864

59-
Set the `server` setting to your master's hostname. The default value is `server = puppet`, so if your master is reachable at that address, you can skip this.
60-
61-
For other settings you might want to change, see [the list of agent-related settings.][agent_settings]
62-
63-
6. Sign certificates (on the CA master)
64-
65-
As each agent runs for the first time, it will submit a certificate signing request (CSR) to the certificate authority (CA) Puppet master. You'll need to log into that server to check for certs and sign them.
66-
67-
- Run `sudo /opt/puppetlabs/bin/puppet cert list` to see any outstanding requests.
68-
- Run `sudo /opt/puppetlabs/bin/puppet cert sign <NAME>` to sign a request.
69-
70-
After an agent's certificate is signed, it regularly fetches and applies configurations from the Puppet master.
71-
72-
## Installing with the GUI
73-
74-
The Puppet installer on macOS provides a graphic user interface to help with manual installation.
75-
76-
1. Double-click the `puppet-agent` disk image you downloaded. This mounts it at `/Volumes/<DMG NAME>`.
77-
78-
A Finder window appears showing the disk's contents: a single `puppet-agent-<VERSION>-installer.pkg` file.
79-
80-
2. Double-click the package file, and follow the installer prompts to install it. When installation finishes, Puppet agent and MCollective will be running.
81-
82-
3. After installing, unmount and delete the disk image.
83-
84-
## Installing on the command line
85-
86-
Alternately, you can use the `hdiutil` and `installer` commands to mount the disk image and install the package from the command line.
87-
88-
1. Mount the disk image by running `sudo hdiutil mount <DMG FILE>`.
89-
90-
2. Locate the `.pkg` file in the mounted volume and install it by running `sudo installer -pkg /Volumes/<IMAGE>/<PKG FILE> -target /`.
91-
92-
When installation finishes, Puppet agent and MCollective will be running.
93-
94-
3. After installing, run `sudo hdiutil unmount /Volumes/<IMAGE>` to unmount the disk image.
95-
96-
4. Optionally, you can then delete the `.dmg` file.
97-
98-
## Upgrading with Puppet
99-
100-
Puppet includes a `package` resource provider for macOS that can install `.pkg` files from a disk image. If you already have Puppet installed, you can use the `puppet resource` command to upgrade with fewer steps.
101-
102-
1. Locate the disk image you downloaded, and note both the filename and its full path on disk. Then, run:
103-
104-
`sudo puppet resource package "<NAME>.dmg" ensure=present source=<FULL PATH TO DMG>`
65+
If you are replacing legacy Puppet packages on the machine, back up `/etc/puppetlabs/`
66+
before you begin. OpenVox continues using the same configuration paths.

0 commit comments

Comments
 (0)