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/
  For Australia region: https://agent.am-ap-southeast.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)

Moveworks Agent Credentials:

• Access Key (Org Name): This is the same as your Customer ID which you should have used when setting up SSO.
• Access Secret: Follow this guide to get the Access Secret from Moveworks Setup.

Installation Method

1. Change the directory to where you need to setup the agent. (Home Directory is recommended)
2. Download the agent installation script using curl or wget
   💡 These links redirect to Github.
   curlwget

   curl -fsSL https://get-agent.moveworks.com > setup_agent.sh
   

   wget https://get-agent.moveworks.com/ --output-document setup_agent.sh  
   

3. Set the script's permissions to allow execution.
   Shell

   chmod +x setup_agent.sh
   

4. Select the runtime between docker and podman and run the script
   Shell

   sudo ./setup_agent.sh --docker
   

   or
   Shell

   ./setup_agent.sh --podman
   

💡 Add sudo only if using Docker. Never use sudo when handling containers with Podman. This applies throughout the document.
💡 To initialise with host network (if ip-forwarding is disabled, or if you get a warning that container cannot access network) use --host-network
This command will install docker or podman if it is not already installed.

5. Configure the Setup

   Example Prompts & Values:

   Prompt	Description	Example Values
   Enter username	Enter the server username you want to install the agent with.	root ubuntu $(whoami)
   Enter the number of Agents to Start	At least 2 agents are recommended to be running in a single server.	1 2 3
   Enter the agent version	The version of the agent which you want to install. (default is the latest)	Check latest version from https://gallery.ecr.aws/moveworks/agent
   Configuration file found. Do you want to set a new configuration? [y/n]:	This only happens when a configuration file already exists. You can choose to re-configure here.	y/n
   Do you want to add required Certificates( If the agent is meant to connect to a Directory system using LDAP)?	You can add Certificates here in the certs directory. Rerun the script for changes to apply.	y/n

   
   

6. Configuring the Agent

   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: 3, if secrets are stored in Azure Key Vault.	1 2 3
   Enter the access_key (org name):	This will be provided by Moveworks, use all lowercase characters when entering the value	Value provided by Moveworks
   Enter the access_secret:	This is the Access Secret that will be provided by Moveworks. If you configured an external secrets manager to store the Access Secret, it will prompt for input, enter secret URI to where the secret is hosted.	Value provided by Moveworks
   Enter the auth_url:	Select the auth_url depending on data center requirements. Confirm with the Moveworks 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 Australia: https://agent.am-ap-southeast.moveworks.com/api/v1/auth
   Enter the config_url:	Select the 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 Australia: https://agent.am-ap-southeast.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), Oauth2 Refresh Token (6), Custom Auth(7)]:	Select the appropriate header decorator (typically for auth). You will then be guided to provide the necessary information for the given header type.	3

Other Tools

1. 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.

   Shell

   ./setup_agent.sh --validate
   

2. Stop all running agents — This will shut down all running agents.

   Shell

   ./setup_agent.sh --stop
   

3. Fetch LDAP certificate from the server (openssl required for this script to work)

   Shell

   ./setup_agent.sh --fetch
   

4. Starting an agent

   Shell

   ./setup_agent.sh --start
   

5. Reconfigure the agent:

   Shell

   ./setup_agent.sh —-configure
   

6. Upgrading the agent: This will upgrade all the agents at the server,

   Shell

   /setup_agent.sh —-upgrade
   

Common Errors and Troubleshooting

When running ./setup_agent.sh and the following is observed:

Failed to enable unit: Unit file docker service does not exist
[ERROR] Error enabling Docker service to start on boot
Failed to start Docker service: Unit docker service not found
[ERROR] Error starting Docker service

There may be an issue with the docker installation, to confirm do the following

• Run the docker logs
  • Shell

    docker logs --follow
    

  • See if the following error is observed:
    • Shell

      exec /bin.sh: operation not permitted
      

  • If it is, uninstall docker and reinstall by following the steps for installing with the docker convenience script

Error installing Podman. Install Podman and Rerun
Error installing Docker, Install Docker and Rerun

The script allows Docker/Podman installation only for select Linux Distributions. Manually install Docker/Podman and then rerun the script with the same options.

Error adding Podman repository to package sources. Install Podman and Rerun
Error adding GPG key for Podman repository. Install Podman and Rerun

Ubuntu versions lower than 20.10 don't support Podman via the official repository. Manually install Docker/Podman and then rerun the script with the same options.

Error installing yum-utils to install docker. Install docker and Rerun

For non s390x RHEL based distributions, we need to add yum-utils to install Docker. Manually install Docker/Podman and then rerun the script with the same options.

Error enabling linger
Loginctl not installed. Error enabling linger

If loginctl is not installed, script will continue installation.
It may not be an issue with Docker based containers but for Podman, Agent might stop running when user session ends/dies.

Warning: System does not use systemd. Docker service may not start on boot

If systemctl is not installed, there may be issues with the the Docker/Podman container restarting on boot.

Podman version $podman_version does not meet the minimum required version $PODMAN_VERSION. Please upgrade Podman
Docker version $docker_version does not meet the minimum required version $DOCKER_VERSION. Uninstall Docker and rerun.

If docker/podman is installed and the versions don’t meet the minimum requirement, it will give a warning for the same.

Error creating directory /etc/systemd/system. Create the directory and Reru
Error creating directory $HOME/.config/systemd/user. Create the directory and Rerun

For Podman containers, systemd file needs to be added to this directory. If this directory does not exist, we create said directory. If the operation fails, manually create that directory and rerun the script with the same options.

Error renaming Podman container CONTAINER_NAME to moveworks_agent_{i}
Error generating systemd unit file for Podman container moveworks_agent_

Check old/unused containers/networks/volumes and remove them `podman system prune` 

Error reloading systemd daemon for Podman containers
Error enabling service for Podman container moveworks_agent_
"Error disabling or stopping service for Podman container
Error reloading systemd daemon for Podman containers.

Check whether systemd is correctly installed and functional.

Error: Failed to pull agent image with version '$AGENT_VERSION' using podman from ECR repository '$ECR_URL'.

Check whether entered version is correct and the image corresponding to the version exists at https://gallery.ecr.aws/moveworks/agent

Sample Moveworks Agent Configurations

LDAPS only (port 636)

bond_version: 2.10.1 # 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.10.1 # 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

LDAPS + Jira + Confluence + Azure Key Vault

bond_version: 2.10.1 # This will be set automatically by the configuration tool
ldap_config:
  enabled: true
  host: mvwks.net
  ldap_service_password:
    azure_entry:
      secret_name: mw-ldap-secret
  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:
          azure_entry:
            secret_name: mw-jira-secret
        username: jira-moveworks
    service: JIRA
  CONFLUENCE:
    enabled: true
    header_decorators:
    - basic_auth:
        password:
          azure_entry:
            secret_name: mw-confluence-secret
        username: confluence-moveworks
    service: CONFLUENCE 
secrets_provider_config:
  azure:
    default_vault: https://agent-dev-vaulxt.vault.azure.net/