Deploy with Chef

This guide provides a complete Chef cookbook for installing and enrolling LinuxGuard. Credentials are managed with chef-vault, which encrypts data bag items using each node's public key so only authorised nodes can decrypt them. The recipe is idempotent — safe to run on already-enrolled nodes because the enroll resource includes a not_if guard on /var/lib/linuxguard/config.

Prerequisites

• Chef Workstation installed on your workstation

• Chef Infra Server with nodes registered and their public keys uploaded

• The chef-vault gem available on your workstation (chef gem install chef-vault if not already installed)

• A LinuxGuard API key and tenant ID (from the LinuxGuard console)

Important: chef-vault requires Chef Infra Server with public/private key pairs per node. It is not compatible with chef-solo or knife-solo. If you are using chef-solo or chef-zero, use the Chef secret() helper (available in Chef Infra Client 17.5+) to integrate with AWS Secrets Manager or Azure Key Vault instead.

Cookbook Structure

Create the following structure in your Chef repository's cookbooks/ directory:

cookbooks/
└── linuxguard/
    ├── metadata.rb          # Cookbook name, version, description
    ├── attributes/
    │   └── default.rb       # Default attribute values
    └── recipes/
        └── default.rb       # Install, enable, enroll

Step 1: Create the chef-vault Item

Store LinuxGuard credentials in a chef-vault item. The vault encrypts the data bag item using the public keys of the nodes you specify — only those nodes can decrypt it during a Chef run.

Run the following command from your workstation:

knife vault create linuxguard credentials \
  '{"api_key":"<API_KEY>","tenant_id":"<TENANT_ID>"}' \
  --search "role:linuxguard-node" \
  --admins "admin"

• --search — specifies which nodes should have decryption access. Adjust the search query to match the nodes in your environment (for example, role:linuxguard-node or name:*).

• --admins — specifies Chef Server users who can administer the vault item (read, update, delete).

To verify the vault item was created:

knife vault show linuxguard credentials

Step 2: Create the Cookbook Files

metadata.rb

name             'linuxguard'
maintainer       'Your Organization'
maintainer_email '[email protected]'
license          'All Rights Reserved'
description      'Installs and enrolls LinuxGuard agent'
version          '1.0.0'

chef_version '>= 16.0'

attributes/default.rb

# Default attributes — override in roles or environments as needed
default['linuxguard']['installer_url'] = 'https://packages.linuxguard.io/install-linuxguard.sh'

recipes/default.rb

# Install LinuxGuard agent
execute 'install_linuxguard' do
  command "curl -fsSL #{node['linuxguard']['installer_url']} | bash -s -- --yes"
  not_if { ::File.exist?('/usr/bin/linuxguard-agent') }
end

# Enable and start LinuxGuard service
service 'linuxguard-agent' do
  action [:enable, :start]
end

# Retrieve credentials from chef-vault
linuxguard_creds = chef_vault_item('linuxguard', 'credentials')

# Enroll LinuxGuard agent (idempotent via not_if guard)
execute 'enroll_linuxguard' do
  command lazy {
    "linuxguard-agent enroll " \
    "--api-key=#{linuxguard_creds['api_key']} " \
    "--tenant-id=#{linuxguard_creds['tenant_id']}"
  }
  not_if { ::File.exist?('/var/lib/linuxguard/config') }
  sensitive true
end

Note: The not_if { ::File.exist?('/var/lib/linuxguard/config') } guard skips enrollment if the agent is already enrolled. The sensitive true attribute prevents credentials from appearing in Chef run logs. See Automated Deployment Overview for details on the agent's built-in idempotency behavior.

Step 3: Add the Cookbook to a Run List

Add the cookbook to a node's run list:

knife node run_list add <NODE_NAME> recipe[linuxguard]

Or add recipe[linuxguard] to a role's run list so all nodes in that role receive the cookbook automatically:

knife role edit linuxguard-node

Then run the Chef client on the target node to apply the cookbook:

chef-client

Verifying the Deployment

After the Chef run completes, you can add a verification step to your recipe to confirm the agent is running:

# Verify LinuxGuard agent service is running
ruby_block 'verify_linuxguard_running' do
  block do
    status = `systemctl is-active linuxguard-agent`.strip
    raise "LinuxGuard agent is not running (status: #{status})" unless status == 'active'
  end
  only_if { ::File.exist?('/var/lib/linuxguard/config') }
end

Enrolled nodes also appear in the Infrastructure view of the LinuxGuard console within a few minutes of successful enrollment.

---

Related: Automated Deployment Overview | Installation | Configuration