VMware
Configuration of PPA should take around 15 minutes.
You will:
- Configure networking.
- Setup an SSH key.
- Set a strong admin password.
- Provide an Active Directory server for user authentication.
Setting a password for the VMware Console (optional)
We recommend using VMware permissions to limit access to the console – one less password to remember!
If you are not using VMware permissions and wish to password-protect the virtual terminal, run:
passwd
Once a password has been configured the terminal will automatically log out after 3 minutes of inactivity.
Setting a static IP address for VMware
After deploying the virtual machine it is good practice to set a static IP address for the appliance.
Note
To complete this step you will require:
- An available static IP address
- Routing and DNS settings
Connect to the virtual machine's Console to access a command prompt.
If DHCP is configured to return settings that are applicable in a static context, helpful commands when configuring a static IP address include:
Command | Description |
---|---|
ip route | grep default |
Print the default gateway set by DHCP |
ip addr show eth0 |
Print the current IP address and netmask |
cat /etc/resolv.conf |
Show the current DNS settings |
Run sudo netconf
to start the network setup utility:
Once configuration is complete, run sudo reboot
when prompted. This will restart PPA with the new IP address.
Securing the appliance
After configuring the network, the next step is to secure it.
Connect to the appliance with a web-browser using the IP address shown in Vsphere or the cloud provider console.
PPA creates a self-signed certificate on first boot that will be reported as insecure by browsers:
Manually verify that the connection is secure by viewing the certificate:
Scroll down and verify that the SHA256 fingerprint:
...matches the output of the fingerprint
command:
Note
You can run the fingerprint
command via the web console for VMware, console for HyperV, or via SSH for AWS or Azure.
When you are satisfied that the connection is secure, trust the certificate and proceed to the appliance's web UI.
Setting a master key for VMware
The first SSH connection to PPA will set a master key. PPA will pick a random username for this initial connection.
Note
Additional keys can be added after setup.
Grab the ssh command from the web UI and run it locally in PowerShell or Terminal:
If you have not used SSH before you may have to generate an SSH key pair:
ssh-keygen -t rsa
On connecting, the appliance should report that your key has been added:
The appliance will add your public key to /var/disk/config/authorized_keys
Future SSH connection should be made with the username support
.
Admin password
Back in the web-browser, PPA will ask you to choose a strong password for the admin
local account:
The admin
account has complete control over the appliance. It is recommended that you generate a strong password and store it in a vault or password manager, then switch to using an Active Directory account for everyday access to PPA.
Vault Setup
PPA will now offer to configure a local Hashicorp Vault for you:
Most tasks use the vault to securely store and retrieve secrets. If you already have an existing vault you wish to use you can skip this step and configure it later.
If you click "Setup Vault", PPA will take care of initial setup for you and allow you to download the master keys to the vault:
Put these in a safe place! You will need them when you reboot PPA.
Active Directory
[Recommended]
PPA can authenticate Active Directory users using LDAPS.
Note
To complete this step you will require:
- The active directory domain you wish to use for authentication, plus the host and LDAPS port if it is not resolvable
- The sAMAccountNames for list of groups you wish to allow access to PPA, e.g:
All Users
Login to the web interface as admin and then click on the 'Configuration' menu item. Find the Active Directory tile and click the 'Configure' button:
This will open a four-step web form:
Network settings
You will need to provide the following information:
Setting | Description | Default |
---|---|---|
Domain | The domain used by Active Directory | None |
Host | The host and port LDAPS is listening on. | The host returned by a DNS lookup for Domain |
Active Directory Credentials
You will need to provide a username and password to access Active Directory. These credentials will not be saved on the appliance.
Organizational Units of Interest
You can select organisational units from the dropdown menu. Or you can leave the selection empty to select all groups. Then click Import Security Groups to fetch groups.
Save configuration
Check that PPA has managed to retrieve the correct number of security groups. Then click Save to save the configuration.
Optional Configuration
Installing custom HTTPS certificates
[Advanced, Optional]
Replace the files at /var/disk/certs/https.key
and /var/disk/certs/https.crt
.
You can use ssh
:
tar -c https.key https.crt | ssh support@<address> -C "tar -x --no-same-owner -C /tmp/"
ssh support@<address> -C "sudo mv /tmp/https.* /var/disk/certs/https.*"
or edit the files using vim
or nano
.
Reboot the appliance.
Configuring HashiCorp Vault
[Recommended, Optional]
PPA comes with a copy of HashiCorp Vault running on port 8200.
Navigating there with a browser will take you to the initial setup wizard.
Here you will create keys that will be required whenever PPA is restarted or the vault is sealed.
Warning
Put your keys in a safe place! Losing your keys will permanently lock you out of the vault.
Recommended configuration:
Environment | Key Share | Key Threshold |
---|---|---|
Development | 1 | 1 |
Production | 3 | 5 |
Once the initial setup is complete and the vault unsealed you can now add it to PPA.
Back in PPA, click the Vaults section and select Add Vault.
Network monitoring with SNMP
[Optional]
PPA supports SNMP for network monitoring. The SNMP agent can be configured by replacing the file at /var/disk/config/snmpd.conf
. The default configuration provides read-only access to the standard MIBs.
Warning
Make sure that your SNMP Manager can communicate with the SNMP agent running on PPA. It will require access on port 161 via UDP.
To customise the SNMP configuration you can use ssh
to connect to the appliance, and then edit the file using vim
or nano
.
Reboot the appliance to propagate your changes.
Logging to an external Syslog server
[Optional]
PPA can be configured to send logs to an external Syslog server, providing a comprehensive audit trail for all user activity.
-
Navigate to the PPA Configuration page, and hit 'Configure' on the Syslog card.
-
Add the correct Host, Protocol and Certificates (if required), and check enabled.
You should now be able to view the PPA logs in your Syslog server.
Warning
Make sure that PPA is permitted to communicate with your Syslog server on the correct port and protocol.
You can read more about the log messages emitted by the appliance at Event Logging with PPA.
Sending emails with SMTP
[Optional]
PPA can be configured to use an external SMTP server to send emails as part of a task workflow.
- Navigate to the PPA Configuration page, and hit 'Configure' on the SMTP card.
- Add the correct settings including authentication credentials (if required).
You can now use the SMTP server in your tasks with the Events Module - Notification Functions.
Single sign-on with SAML
[Optional]
PPA can be configured to enable SSO with SAML.
- Navigate to the PPA Configuration page, and hit 'Configure' on the SAML card.
- Add the correct Identity Provider Metadata URL, Service Provider Entity ID, Encryption Key and Encryption Certificate (if Assertion Encryption required), and check enabled.
- You can optionally provide a Signing Key and Signing Certificate. If none provided, PPA will auto-generate them.
The following attribute statements are required in the assertions sent by your Identity Provider:
Attribute Statements
- username and object_sid: Must reflect the equivalent Active Directory fields so that PPA can correctly match a user login via SAML to an AD user.
- name and email: Recommended.
Group Attribute statements
- groups: Must reflect the user information held in Active Directory, since PPA uses AD groups to determine user roles and permissions
Warning
Identity Providers sometimes use different terminology for common SAML concepts. You will probably need to read the documentation for your particular IDP to work out how to integrate with PPA.
Testing single sign-on
- Navigate to the PPA root domain, and you should be automatically redirected to authenticate with your IDP.
- Following authentication with your IDP, you should be redirected back to PPA.
If you need to bypass SSO for debug purposes you can use the following to sign-in with username/password:
https://${PPA_ROOT_DOMAIN}/ui/?skipSSO=true
.
Enabling Kerberos Authentication Support in tasks
[Optional]
PPA can be configured to generate a Kerberos ticket-granting ticket (TGT) that can be used for authenticating to devices as part of a task.
- Navigate to the PPA Configuration page, and hit 'Configure' on the Kerberos card.
- Add the correct settings including authentication credentials.
- You can optionally provide a custom configuration to be used when generating the TGT.
You can now use Kerberos authentication in tasks by enabling 'Use Kerberos' in the Playbook Metadata form.
Note: If a custom configuration is not provided, a configuration will be automatically generated.
Complete
After setting a password for admin
you will be asked to log in.
Setup is now complete.