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

Generating a key pair

If you have not used SSH previously you will probably need to generate a new SSH key pair.

Linux/macOS

You can use ssh-keygen to generate a new key pair.

Just make sure that you don't accidentally overwrite an existing key pair, especially if you are working on a shared machine.

ssh-keygen -t rsa

Windows

You can use PuTTYgen to generate a new key pair.

• Click Generate to start.

• We recommend adding a key passphrase, although this is optional.

  Don't forget to make a note of the passphrase. You will need it when using your key to connect to PPA.

• Click Save private key to save the generated key.

Providing your public key to PPA

PPA will pick a random username for the first connection. This connection will be used to save your public key to PPA, allowing you to securely access the appliance via SSH.

Note

Additional keys can be added after setup.

Open the web UI and make a note of the SSH setup command e.g. ssh setup-WtoFCRzH@10.9.206.103

Linux/macOS

Run the SSH setup command on your local machine in your terminal.

On connecting, the appliance should report that your key has been added:

Windows

You can use PuTTY to connect to the appliance.

• Provide the host and port and select SSH connection type.

• Select the private key file that you created earlier with PuTTYgen for authentication.

• Click Open to make the connection, and provide the username from the SSH setup command e.g. setup-WtoFCRzH

• On connecting, the appliance should report that your key has been added:

Adding additional keys

PPA has added your public key to /var/disk/config/authorized_keys. You can append additional public keys to this file to allow other administrators access.

Connecting via SSH

Once the SSH key setup process is complete, all future connections should be made with the username support e.g. ssh support@10.9.206.103

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.

Changing the admin password

You can change the admin password later on if required.

Connect to the appliance via SSH ssh <username>@<address> and run changeAdminPasswd to open the password change utility.

Tip

Make sure you use the correct username for the SSH connection.

It varies dependent on the particular environment (VMware, Azure, or AWS).

Vault Setup

[Recommended]

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.

Warning

Make sure you put the master keys in a safe place! You will need them to unseal the vault whenever you reboot PPA.

Licence Setup

[Recommended]

Adding a licence will allow multiple users to start tasks. (In evaluation mode only the admin user can start tasks).

If you have a licence, you can upload it here. Alternatively, you can add one from the Configuration page later.

Active Directory Setup

[Recommended]

Configuring Active Directory will allow users to sign into PPA using their standard Active Directory credentials.

PPA also uses Active Directory security groups to delegate access to tasks, roles, and permissions to groups of users.

Basic Configuration

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.

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

If you know the settings for your Active Directory service you can provide them here. Alternatively, you can do this from the Configuration page later.

Test Connection

We recommend testing the connection to Active Directory by clicking the 'Test Connection' button.

You will be asked to provide a username and password to test authentication. These credentials will not be saved on the appliance.

Click 'Save' to save the domain and host settings.

Task Setup

[Recommended]

PPA includes a selection of example tasks for automating common Active Directory operations.

Installing these tasks as part of the setup process means they will be ready to use when you first sign in to PPA.

Alternatively, all of our Active Directory tasks, plus a wide range of examples for integrating with other third party services, can be downloaded from the Resource Hub later.

Active Directory Configuration

Importing Groups

Navigate to the PPA Groups page, and click the 'Import Groups' button to open a two-step dialog:

Credentials

You will need to provide a username and password to search for groups in Active Directory.

If you are logged in as a domain user, you can opt to use your current Active Directory credentials.

If not, you will need to provide credentials. These credentials will not be saved on the appliance.

Find Groups

You can search for groups by name or search for groups within a particular Organizational Unit. You can move groups to and from the 'Selected' list using the 'Add' and 'Remove' buttons.

• When you are happy with the 'Selected' list, click 'Import' to add groups to PPA.

Note

Users will not be synchronised from these groups, and must be imported from the Users page.

Importing Users

Navigate to the PPA Users page and click the 'Import Users' button to open a three-step dialog:

Credentials

You will need to provide a username and password to search for users in Active Directory.

If you are logged in as a domain user, you can opt to use your current Active Directory credentials.

If not, you will need to provide credentials. These credentials will not be saved on the appliance.

Find Users

You can search for users by name, or search for users within a particular Security Group or Organizational Unit. You can move users to and from the 'Selected' list using the 'Add' and 'Remove' buttons.

When you are happy with the 'Selected' list, click 'Next'.

User Summary

You can set each user's Authentication Type (if applicable) & "Can Start Tasks" permission (if you have available seats on your licence) from the User Summary.

When you are happy with the user settings, click 'Import' to add users to PPA.

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 <username>@<address> -C "tar -x --no-same-owner -C /tmp/"

ssh <username>@<address> -C "sudo mv /tmp/https.* /var/disk/certs/https.*"

or edit the files using vim or nano.

Reboot the appliance.

Tip

Make sure you use the correct username for the SSH connection.

It varies dependent on the particular environment (VMware, Azure, or AWS).

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 click '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 click '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 click '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 Users page and set your AD domain user to use SAML authentication.
• Logout then attempt to login with your AD domain user and you should be automatically redirected to authenticate with your IDP.
• Following authentication with your IDP, you should be redirected back to PPA.

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 click '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.