Prerequisites

Provided by the Customer:

URL of the AD Domain controller or load balancer that the agent should connect to
LDAP/AD Service account username & password (Only applicable for customers using On-Premises Active Directory, LDAP, etc)
REST Service account username & password (Only applicable for customers using On-Premise Jira, Confluence, Sharepoint, etc)
Firewall rules or HTTP Proxy settings in place to allow for outbound communication to https://public.ecr.aws and, to the Agent URL depending on region:
For US Commercial region: https://agent.moveworks.com/
For US GovCloud region: https://agent.moveworksgov.com/
For EU region: https://agent.am-eu-central.moveworks.com/
For Canada region: https://agent.am-ca-central.moveworks.com/
Base 64 encoded .pem cert file for LDAPS connection (typically this is the root cert in base64 format)
Two virtual machines per recommended specifications for High Availability setup (see System/Server Requirements section)

Pre-installation steps:

Install the latest version of Docker or Podman on the server using the instructions from the Docker Website for your OS.
Ensure the Docker (or Podman) daemon is configured to start on boot.

🚧
DO NOT use the snap installation of Docker

Provided by the Moveworks Customer Success team:

Org name
Org Access Secret

Installation

Following the receipt of the encrypted email from your Moveworks Customer Success Team, proceed with the following steps to install the Moveworks agent on your Linux virtual machine(s).

📘
Podman customers
If using podman instead of docker, substitute podman for all of the docker commands in the following instructions

Create a moveworks folder in the server's home directory. After creating, open the moveworks folder.
```
mkdir moveworks
cd moveworks
```
Pull Container Image from Public ECR Repository: Retrieve the latest Docker image of the agent from the public AWS ECR (Elastic Container Registry) repository by running the following command from the moveworks folder.
```
docker pull <version>
```
In the command above replace <version> with the latest version from the public ECR Repo. You can click the copy button on the link above, to grab the latest version.

Copy the helper script from the container to your virtual machine by running the following commands

docker create --name temp <version> # create a readable container layer
docker cp temp:/moveworks/services/bond/runtime/scripts/helper.sh ./helper.sh # copy the file from the temp layer
docker rm -f temp # remove the temp layer

Setup Agent folders & permissions (Note: Some of these operations may require administrative privileges (sudo) to complete.)

sudo ./helper.sh --init # This creates a folder structure for storing agent configs, logs, etc.
sudo ./helper.sh --permissions # This ensures proper permissions are set on the VM for the agent to run

Configure the Agent: Run the command ./helper.sh --configure This command initiates an interactive guide to help you through the configuration process by asking you the questions in the table below. This step enables you to provide specific settings and preferences for the agent's operation. Note: This step is not required if you have received a pre-configured configuration file from your Moveworks Customer Success team. In this case, simply place the configuration file in the conf directory.

Example Prompts & Values:

Prompt	Description	Example Values
Do you want to configure an external secrets manager? [No(1), AWS Secrets Manager(2), Azure Key Vault(3)]:	Select an option depending on how the service account credentials are created. For example: `1`, if account is created on Active Directory.	`1` `2` `3`
Enter the access_key (org name):	This will be provided by your Customer Success team, use all lowercase characters when entering the value	`Value provided by Moveworks`
Enter the access_secret:	This is the Moveworks Org Access Secret that will be provided by your Customer Success team. If you configured an external secrets manager to store the Org Access Secret, it will prompt for the secret URI to where the secret is hosted.	`Value provided by Moveworks`
Enter the auth_url:	Select an `auth_url` depending on data residency requirements. Confirm with the Customer Success team, if unsure.	For - US Commercial: `https://agent.moveworks.com/api/v1/auth` US GovCloud: `https://agent.moveworksgov.com/api/v1/auth` Canada: `https://agent.am-ca-central.moveworks.com/api/v1/auth` EU: `https://agent.am-eu-central.moveworks.com/api/v1/auth`
Enter the config_url:	Select a `config_url` depending on data residency requirements. Confirm with the Customer Success team, if unsure.	For - US Commercial: `https://agent.moveworks.com/api/v1/config` US GovCloud: `https://agent.moveworksgov.com/api/v1/config` Canada: `https://agent.am-ca-central.moveworks.com/api/v1/config` EU: `https://agent.am-eu-central.moveworks.com/api/v1/config`
Do you want to set up agent to use a proxy? Enter [y/n]:	optional, default is `n`	`y` `n`
Enter the proxy url (leave blank for transparent proxies):
Do you want to use a cert with the proxy? Enter [y/n]:		`y` `n`
[y] Enter the full name of the pem file including the extension:	Enter the full filename of your cert and place the cert in `/certs` directory	`cert.pem`
Do you want to set up an LDAP connector? Enter [y/n]:	Enter `y`, if setting up an Active Directory connection	`y` `n`
Do you want to set up an LDAP forest? Enter [y/n]:	Select this option to configure multiple ldap domains. This will repeat the next few steps depending on how many domains you want to setup.	`y` `n`
Enter the FQDN of the LDAP server (do not include ldap:// prefix):	No protocol prefix or port needed.	`company.net`
Enter the port to use e.g: 389 (LDAP), 636 (LDAPS), 3268 (LDAP Global Catalog), 3269 (LDAPS Global Catalog):	Moveworks recommends port 636 for LDAPS, you can use port 389 for LDAP for testing purposes during the initial setup.	`636`
Enter the LDAP service account username:	For Active Directory, LDAP Service User is formatted as a netbios domain name with a backlash and then the service account svc_moveworks` Please note that this may sometimes require escaping, e.g.`MVWKS ame.	`MVWKS\svc_moveworks`
Enter the ldap service password:	Please type (do not paste) the password. This is then encrypted before being saved to disk. The password is masked on entry so you will not see characters as you type.	service account password
Do you want to set up LDAP to connect with SSL? Enter [y/n]:	`y` will allow you to add the local path to your cert (`.pem` file)	`y` `n`
Do you want LDAP to connect with a cert (.pem file)? Note: this is required for LDAPS connections Enter [y/n]:	`y` will allow you to add the local path to your cert (`.pem` file)	`y` `n`
Enter the full name of the pem file including the extension:	Enter the full filename of your cert and place the cert in `/certs` directory	`company_cert.pem`
Do you want to use StartTLS (this is usually when using port 389) Enter [y/n]:	If you are using `LDAPS` with port `636`, this should be `n` Only choose `y` if you want to use port `389` with `startTLS` option.	`y` `n`
Do you want to set up a REST connector? Enter [y/n]:	`n` - not needed for LDAP-only integration `y` - setup REST connection	`y` `n`
Enter the service name (Ex. JIRA, CONFLUENCE, CHERWELL, SHAREPOINT, MSTEAMS, MANAGE_ENGINE, SNOW):	Enter the appropriate service name.	`JIRA`
Do you want to setup a header decorator? Enter [y/n]:	`y` - in order to set up authentication for the REST connection	`y`
What type of header decorator? [KV pair(1), file(2), basic auth(3), Oauth2 Client Credentials(4), Oauth2 Client Credentials Basic Auth (5), custom auth(6)]:	Select the appropriate header decorator (typically for auth). You will then be guided to provide the necessary information for the given header type.	`3`

Add required certificates: If the agent is meant to connect to a Directory system using LDAPS then add the root certificate to the following directory as a .pem file /moveworks_agent/certs .
Start the Agent: This command starts the agent on the customer VM.
```
./helper.sh --start
```
1. For deployments requiring FIPS compliance use --fips flag
```
./helper.sh --start --fips
```
Verify the agent has started successfully by running docker ps

Also, ensure that there are no errors in the agent logs by running tail -f logs/moveworks.agent.<container_id>.INFO.log
Start a second Agent: Once you have verified the Moveworks agent has started successfully, Moveworks recommends starting another agent so that there are at least 2 agents running on the VM. This helps improve stability and reliability of the agent.

📘
Note: For ServiceNow Connections
If you are routing ServiceNow traffic through your Moveworks agent, Moveworks recommends running 4 VMs with 1 agent each.

Helpful Tools

Some helpful scripts are shipped as part of a helper script in the agent package.

Validate OS version & Connectivity - This command will validate the operating system version, check for connectivity to Moveworks servers, and ensure required folders and permissions are set.
```
./helper.sh --validate
```
Stop all running agents — This will shut down all running agents.
```
./helper.sh --stop
```
Fetch LDAP certificate from the server (openssl required for this script to work)
```
./helper.sh --fetch
```

Reconfiguring the Agent

If you need to edit the config simply open the config file with a text editor and edit the fields you need.

Navigate into into the conf directory e.g: cd conf
Open the agent_config.yml with your favorite text editor such as vi or nano e.g: vi agent_config.yml
For sensitive fields like passwords, simply remove the encrypted_value field and replace it with the value field and the actual value in plaintext (this will automatically get encrypted on startup of the agent).
```
moveworks_config:
	...
	moveworks_access_secret:
		value: newOrgAccessSecretValue
ldap_config:
	...
	ldap_service_password:
		value: newldappassword
```
Once the agent_config.yml file has been updated with the new credentials, be sure to restart the current container. You can do this by executing the built-in commands ./helper.sh --stop followed by ./helper.sh --start from the moveworks folder.

Updating the Agent

Stop currently running agents. You can use the script under the tools directory.
```
./helper.sh --stop
```
Pull the latest docker image from ECR public repo.
```
docker pull <version>
```
Initialize the agent - Run the init command to rename the version as the latest.
```
./helper.sh --init
```
Restart the Moveworks agent - If there were multiple agents running just run this command again to start additional agents.
```
./helper.sh --start
```
Verify the agents have started up successfully - Run docker ps to ensure the agents are healthy.

Verify there are no errors in the logs

tail -f logs/moveworks.agent.<container_id>.INFO.log

Sample Moveworks Agent Configurations

LDAPS only (port 636)

bond_version: 2.8.5 # This will be set automatically by the configuration tool
ldap_config:
  enabled: true
  host: mvwks.net
  ldap_service_password:
    encrypted_value: [REDACTED]
  path_to_cert: /home/moveworks/agent/certs/cert.pem
  port: 636
  service_user: MVWKS\svc_moveworks
  use_ssl: true
moveworks_config:
  access_key: moveworks
  auth_url: https://agent.[MOVEWORKS DOMAIN].com/[REDACTED]
  config_url: https://agent.[MOVEWORKS DOMAIN].com/[REDACTED]
  moveworks_access_secret:
    encrypted_value: [REDACTED]

LDAPS + Jira

bond_version: 2.8.5 # This will be set automatically by the configuration tool
ldap_config:
  enabled: true
  host: mvwks.net
  ldap_service_password:
    encrypted_value: [REDACTED]
  path_to_cert: /home/moveworks/agent/certs/cert.pem
  port: 636
  service_user: MVWKS\svc_moveworks
  use_ssl: true
moveworks_config:
  access_key: moveworks
  auth_url: https://agent.[MOVEWORKS DOMAIN].com/[REDACTED]
  config_url: https://agent.[MOVEWORKS DOMAIN].com/[REDACTED]
  moveworks_access_secret:
    encrypted_value:[REDACTED]
rest_configs:
  JIRA:
    enabled: true
    header_decorators:
    - basic_auth:
        password:
          encrypted_value: [REDACTED]
        username: service-moveworks
    service: JIRA

Moveworks Agent Installation Guide

Prerequisites

Provided by the Customer:

Pre-installation steps:

🚧
DO NOT use the snap installation of Docker

Provided by the Moveworks Customer Success team:

Installation

📘
Podman customers

📘
Note: For ServiceNow Connections

Helpful Tools

Reconfiguring the Agent

Updating the Agent

Sample Moveworks Agent Configurations

LDAPS only (port 636)

LDAPS + Jira

Prerequisites

Provided by the Customer:

Pre-installation steps:

🚧DO NOT use the snap installation of Docker

Provided by the Moveworks Customer Success team:

Installation

📘Podman customers

📘Note: For ServiceNow Connections

Helpful Tools

Reconfiguring the Agent

Updating the Agent

Sample Moveworks Agent Configurations

LDAPS only (port 636)

LDAPS + Jira

🚧
DO NOT use the snap installation of Docker

📘
Podman customers

📘
Note: For ServiceNow Connections