--- title: Moveworks Agent Installation Guide excerpt: This document walks through the steps to install the Moveworks agent deprecated: false hidden: false metadata: title: '' description: '' robots: index next: description: '' --- # Prerequisites ## System/Server Requirements The Moveworks Agent runs on Linux. Recommended OS with the following requirements (which are the same as "t3.medium" if hosted in AWS or a “B2” if hosted in Azure): * 4 GB RAM * 2 CPUs * 30 GB of disk space ## OS Requirements: * VM with Ubuntu 20.04 and above OR RHEL 8.0 and above. * Latest Version of Docker Engine or Podman must be pre-installed. ## Server Setup * Procure server(s) matching the requirements outlined above. Note: Moveworks recommends at least 2 servers for high availability (HA). * Set up the Server with Docker or Podman. Note: Podman is recommended for a fully root-less implementation. * _**Recommended:**_ If possible, Moveworks recommends that you use a separate (non-root) user for running the Moveworks Agent. This limits the granting of unintended access rights for the Agent. ## Network Requirements * Ensure the server has proper network access to the on-premises system you intend Moveworks to connect to. * Ensure the server has proper network access upstream to the Moveworks Platform. * Note: You can run the following curl command on the server to verify connection works: `curl ` If Network connection is set up correctly, you should receive `404 page not found` as the response. * auth_url to be used: * For US commercial region: `https://agent.moveworks.com/api/v1/auth` * For US GovCloud region: `https://agent.moveworksgov.com/api/v1/auth` * For EU region: `https://agent.am-eu-central.moveworks.com/api/v1/auth` * For Canada region: `https://agent.am-ca-central.moveworks.com/api/v1/auth` * For Australia region: `https://agent.am-ap-southeast.moveworks.com/api/v1/auth` * 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/` ## Credentials and Information 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 Authentication _(Only applicable for customers using On-Premise Connections to make REST API Calls i.e. Jira, Confluence, Sharepoint, etc)_ * Base 64 encoded `.pem` cert file for LDAPS connection (typically this is the root cert in base64 format) ## 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:** To get the Access Secret, you must first generate it from the Agents module in Moveworks Setup: 1. Navigate to the Agents module in the left navigation bar under Core Platform. ![](https://files.readme.io/ecfbe3221b2fcae89738fadd61a32b498ea67a4969282c4d5d18e1a2d38c9c5b-image.png)
2. Click on the Generate Secret button in the bottom right. A pop-up window will appear showing the `Org Access Secret`. 3. Copy the Org Access Secret and save it. **You will need this value for the installation script.** **IMPORTANT**: Secure Your Org Access Secret Please be advised that the API token for the Org Access Secret is displayed only once. It is imperative that you save it immediately for future use. Please handle the secret securely, and do not share it in plain text.
## 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. ```Text curl curl -fsSL https://get-agent.moveworks.com > setup_agent.sh ``` ```Text wget wget https://get-agent.moveworks.com/ --output-document setup_agent.sh ``` 3. Set the script's permissions to allow execution. ```Text Shell chmod +x setup_agent.sh ``` 4. Select the runtime between docker and podman and run the script ```Text Shell sudo ./setup_agent.sh --docker ``` or ```Text 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 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](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
If the script fails to fetch the Agent Image from ECR, you can resolve this issue by following the steps [here](/docs/moveworks-agent-installation-guide#/fetching-the-agent-image-without-ecr) 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 Tenant Settings > General Information > Org Name
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. Generate this in Moveworks Setup by following the [instructions mentioned here](/docs/moveworks-agent-installation-guide?isFramePreview=true#moveworks-agent-credentials).
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 an appropriate service name. This name should be representative of the system you are trying to connect to. If you have multiple instances, you can enumerate subsequent service names. (i.e. `JIRA`, `JIRA_2`). Please make note of this name as you'll need to reference it in further steps. `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
7. Create the connector 1. Go to Moveworks Setup ![](https://files.readme.io/879740450be8c73ddd88c8fe3252ec71fbce0da2b9f1fc1ffaea96e588eb38fc-CleanShot_2025-01-06_at_20.16.242x.webp) 2. Select System Connectors or Custom Connectors depending on if the system you have added is used for a built-in functionality or for an Agent Studio use case. ![](https://files.readme.io/a459d5eb2365fbd504dd01e59f5203857a88404341c3b3e2f0d0a7d95e33fbb4-CleanShot_2025-01-07_at_17.16.40.png) 3. Create Connector ![](https://files.readme.io/c426e67419c44a39e7e8bbcce9fb5b3c9d2d013c7f228ab157b22c4971bbeb23-CleanShot_2025-01-06_at_20.18.302x.webp) 4. Select On Premise Auth as the “Auth Config” and enter the Service Name from Step 6. If you are creating a Agent Studio connector, you must enter the Service Name and have it match the config in the agent from Step 6. ![](https://files.readme.io/9a686a4191d8c4fd7c9dbddde85cc25ee1dfff8295fe3e5061aa925ae48e0e3b-CleanShot_2025-01-06_at_20.20.392x.webp) 5. Save your connector. ### Validating the Installation 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. **Check Agent Status** After starting the agent, check the healthiness of the container by running `docker ps` or `podman ps` on the server. ```shell # For Docker sudo docker ps # For Podman podman ps ``` 3. **Start the Agent** ```shell ./setup_agent.sh --start ``` ### Fetching the Agent Image Without ECR In some scenarios, enterprises have Servers with Firewall policies which block the ability for the VM to download the Agent image from ECR and automate the setup process, this is an alternate way to fetch the image in those scenarios. * You can start by visiting the [Moveworks ECR Public Gallery](https://gallery.ecr.aws/moveworks/agent) and download the latest image tag . ``` docker pull public.ecr.aws/moveworks/agent:2.10.4 ``` * Save this image locally by running the command ``` docker save -o moveworks_agent.tar public.ecr.aws/moveworks/agent:2.10.4 ``` * This will save the image as **moveworks_agent.tar** * You can then load the image on the customer Server. ``` docker load -i moveworks_agent.tar ``` Image should show up on the machine on doing docker images Now that the image has been added to the VM we can run the below commands to kick off the container. ``` docker run -d \ -v /path/to/local/conf:/home/moveworks/agent/conf \ -v /path/to/local/certs:/home/moveworks/agent/certs \ -v /path/to/local/logs:/var/log/moveworks \ -e LOG_LEVEL=INFO \ public.ecr.aws/moveworks/agent:2.10.4 ``` ### Other Tools 1. **Stop all running agents —** This will shut down all running agents. ```shell ./setup_agent.sh --stop ``` 2. **Fetch LDAP certificate from the server **([openssl](https://www.openssl.org/) required for this script to work) 3. **Reconfigure the agent**: ```Text Shell ./setup_agent.sh —-configure ``` 4. **Upgrading the agent**: This will upgrade all the agents at the server, ```Text Shell ./setup_agent.sh —-upgrade ``` ### Common Errors and Troubleshooting When running ./setup_agent.sh and the following is observed: ```shell 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](https://docs.docker.com/engine/install/ubuntu/#install-using-the-convenience-script) ```jsx Shell 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. ```jsx Shell 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 22.04 don't support Podman via the official repository. Manually install Docker/Podman and then rerun the script with the same options. ```jsx Shell 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. ```jsx Shell 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. ```jsx Shell 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. ```jsx Shell 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. ```jsx 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. ```jsx 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**`](https://docs.podman.io/en/stable/markdown/podman-system-prune.1.html)  ```jsx 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. ```jsx 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](https://gallery.ecr.aws/moveworks/agent) ## Sample Moveworks Agent Configurations ### LDAPS only (port 636) ```yaml yml 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 ```yaml yml 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 ```yaml yml 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 timeout_ms: 60000 #increase default timeout to 60s. Value is in ms 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/ ```