puppet-octopass

Table of Contents

1. Description
2. Setup - The basics of getting started with octopass
   • Setup requirements
3. Usage - Configuration options and additional functionality
   • Configuring modules in Puupet
   • Configuring modules from Hiera
4. Limitations - OS compatibility, etc.
5. Development - Guide for contributing to the module

Description

The octopass module handles installing and configuring octopass.

Setup

Setup Requirements

The octopass module requires the following puppet module:

• puppetlabs-stdlib: version 4.6.x or newer
• puppetlabs-apt: version 4.x (only Debian-based distributions).

note: puppetlabs-apt is soft dependencies. If you are installing on Debian systems, you will need to configure appropriate versions of this module.

Usage

Configuring modules in Puppet

To set up the octopass in Puppet codes, you can configure like the following:

class { '::octopass':
  token        => 'iad87dih122ce66a1e20a751664c8a9dkoak87g7',
  organization => 'yourorganization',
  team         => 'yourteam',
}

Configuring modules from Hiera

To set up octopass using Hiera, you declare include ::octopass in puppet manifests and configure in Hiera like the following:

include ::octopass

---
octopass::token: iad87dih122ce66a1e20a751664c8a9dkoak87g7
octopass::organization: yourorganization
octopass::team: yourteam

Configure with owner/repository

If you want to use a repository instead of team, you'd set owner and repository:

octopass::token: iad87dih122ce66a1e20a751664c8a9dkoak87g7
octopass::owner: hfm
octopass::repository: puppet-octopass

Change group name

If you want to use other name of group than team or repository, you'd set group:

octopass::token: iad87dih122ce66a1e20a751664c8a9dkoak87g7
octopass::organization: yourorganization
octopass::team: yourteam
octopass::group: othergroupname

For GitHub Enterprise

With GitHub Enterprise, you'd change endpoint:

octopass::endpoint: 'https://git.yourorg.com'

Combination with other modules

Octopass in production requires nsswitch.conf for resolving name, and sshd and PAM like the following:

include ::octopass

# https://forge.puppet.com/trlinkin/nsswitch
include ::nsswitch

# https://forge.puppet.com/ghoneycutt/ssh
include ::ssh

# https://forge.puppet.com/herculesteam/augeasproviders_pam
pam { 'Set sss entry to system-auth auth':
  ensure    => present,
  service   => 'sshd',
  type      => 'auth',
  control   => 'requisite',
  module    => 'pam_exec.so',
  arguments => ['quiet', 'expose_authtok', '/usr/bin/octopass', 'pam'],
}

---
octopass::token: iad87dih122ce66a1e20a751664c8a9dkoak87g7
octopass::organization: yourorganization
octopass::team: yourteam

nsswitch::octopass:
  - files
  - octopass
  - sss
nsswitch::passwd: "%{alias('nsswitch::octopass')}"
nsswitch::shadow: "%{alias('nsswitch::octopass')}"
nsswitch::group: "%{alias('nsswitch::octopass')}"

ssh::sshd_authorized_keys_command: '/usr/bin/octopass'
ssh::sshd_authorized_keys_command_user: 'root'
ssh::sshd_use_pam: 'yes'

Limitations

See operatingsystem_support in metadata.json

Development

Running tests

The octopass puppet module contains tests for both rspec-puppet (unit tests) and beaker-rspec (acceptance tests) to verify functionality. For detailed information on using these tools, please see their respective documentation.

Testing quickstart

• Unit tests:

$ bundle install
$ bundle exec rake

• Acceptance tests:

# Set your DOCKER_HOST variable
$ eval "$(docker-machine env default)"

# List available beaker nodesets
$ bundle exec rake beaker_nodes
centos7
stretch
xenial

# Run beaker acceptance tests
$ BEAKER_set=debian9 bundle exec rake beaker