---
title: "Installation"
canonical: "https://docs.vaultspeed.com/space/VPD/3013640213/Installation"
format: markdown
---
Before using the cloud application, the agent needs to be installed and set up

> Macro (toc)

## Install Java

Install Java (oracle) JDK 8 or Open JDK 11.  
Open JDK 8 might not work out of the box due to missing root certificates ([https://dzone.com/articles/openjdk-10-now-includes-root-ca-certificates](https://dzone.com/articles/openjdk-10-now-includes-root-ca-certificates) ) although you can install them yourself. This issue will cause the following error to show up: `pkix path building failed`

![image2020-11-4_11-8-41.png](media://1bedfc93-2def-464a-8e03-666e933e352e)

## Download the agent

- Log in into VaultSpeed
- Download the agent.zip file by going to the “agent” menu and clicking the Download JAR button.
- This will download a zip file to your local machine.
- Extract this agent.zip file.  The resulting folder contains:
  - log folder, this is where all the log files will be stored.
  - generated_files folder, this is where the code generated by VaultSpeed will be placed (this folder can be moved to another location). This folder contains 2 more folders, failed_files and deployed_files, generations that are executed with the auto-deploy functionality will be copied to these folders on completion/failure.
  - source_metadata folder, this is where the metadata obtained from the source will be stored before sending it to the cloud application (this folder can be moved to another location).
  - **vs-agent.jar**, this is the agent application.
  - client.properties, this is the configuration file for the agent.
  - logging.properties, this is the configuration file for the logger(does not have to be configured).
  - connections.properties, this is the file where u can define your source connections.

## Edit the agent configuration to match your paths

### Change the client.properties file

- Open client.properties with a text editor:
  - At the top of the file, the file location and name for the connections file has to be defined.
  - Configure the file locations of the generated_files and source_metadata folders. these folders do not have to be located in the same folder as client.jar but they have to be readable and writable by the java process.
  - The other things that may be edited is the polling speed, this determines how often the agent will poll the cloud app to see if there is a task waiting for it, and the maximum number of threads, this determines how many agent task can be running at the same time, we recommend 4 or more since deploying code and obtaining metadata can take a while.
  - The cloud application and OAth URL's in this file have to be allowed through the firewall.

> ⚠️ Do not edit any of the **vs.*** and **oauth.*** settings or the agent will not work!

> ⚠️ The changes to the client.properties file will only go into effect after restarting the agent.

> ⚠️ On Windows, make sure to use "\\" instead of "\", and if your path contains spaces or special characters like ";" you also need to surround it with double quotes (").

### Change the logging.properties file

- Open logging.properties with a text editor:
  - in the "# Naming style for the output [file:"](#) section ( java.util.logging.FileHandler.pattern ), configure the directory where you want the log files to be stored. eg: /home/agent/log/vs-java-client-%g.log.

### Add connections to the connections.properties file

- Open connections.properties with a text editor:  
In this file, all connections to external systems are stored such as Database links, Git repositories, etc.  
A connection property is always defined as: <link name>.<property name>=<property value>
  Connections to databases can also be stored in the cloud application but this is not recommended since it is less secure.
  To define a new Database link, add a new line with: <link_name>.url = "<jdbc url>". The formats for the URLs can be found below. The quotes(") are needed if the URL contains spaces or special characters such as ";".  
Instead of defining the username and password in the url like in the above formats, u can also define them separately by adding a new line with: <link_name>.user= <user name> and one with <link_name>.password= <password>.  
Defining the username and password separately can fix some issues with usernames and passwords that contain special characters and make the JDBC URL invalid.

> ℹ️ This file can be changed without restarting the agent.

> ℹ️ Other, more secure methods for storing connections are available, see [https://vaultspeed.atlassian.net/wiki/spaces/VPD/pages/3291381934](https://vaultspeed.atlassian.net/wiki/spaces/VPD/pages/3291381934).

## JDBC URL Formats

see this page: [https://vaultspeed.atlassian.net/wiki/spaces/VPD/pages/3012722714](https://vaultspeed.atlassian.net/wiki/spaces/VPD/pages/3012722714) 

## Firewall configuration

Allow the following URLs through your firewall, both use the default port 443.

- on the EU instance (logon via [http://app.vaultspeed.com](http://app.vaultspeed.com) )
  - [https://app.vaultspeed.com](https://app.vaultspeed.com)
  - [https://idcs-b19b5f8f59b9482f9af96176aff1fca9.identity.oraclecloud.com/oauth2/v1/token](https://idcs-b19b5f8f59b9482f9af96176aff1fca9.identity.oraclecloud.com/oauth2/v1/token)
- on the Australian instance (logon via [http://app-au.vaultspeed.com](http://app-au.vaultspeed.com) )
  - [https://app-au.vaultspeed.com](https://app-au.vaultspeed.com)
  - <u>[https://idcs-0c5c2d04ee924ddb8706b2bddbd7ca4b.identity.oraclecloud.com/](https://idcs-0c5c2d04ee924ddb8706b2bddbd7ca4b.identity.oraclecloud.com/)</u>

And other URL's that might be required for the JDBC drivers of certain databases

> ℹ️ for other environments you can always check the client.properties file of your agent.
> ℹ️ 
> ℹ️ the url’s for “vs.url” and “oauth.url” need to be whitelisted
> ℹ️ 
> ℹ️ If you have a dedicated instance, we will communicate the exact URL’s to whitelist to you during the setup process.

## Run the agent

You can choose to run the agent in the background or in your terminal:

> 📝 We highly recommend making the agent a service, this prevent you from launching it multiple times and will make sure that it keeps running.  
> 📝 One way of achieving this on Linux is by using an application like supervisord ([http://supervisord.org/index.html](http://supervisord.org/index.html) ) which is an easy way of managing multiple processes (e.g. the Agent, the Airflow webserver and scheduler etc.).

### run the agent in the background

#### Windows

<details>
<summary>CMD</summary>

`start javaw -Djava.util.logging.config.file="C:\Users\name\agent\logging.properties" -jar "C:\Users\name\agent\vs-agent.jar" propsfile="C:\Users\name\agent\client.properties" > NUL 2>&1`
</details>

<details>
<summary>PowerShell</summary>

`start javaw -Djava.util.logging.config.file="C:\Users\name\agent\logging.properties" -jar "C:\Users\name\agent\vs-agent.jar" propsfile="C:\Users\name\agent\client.properties" > $NUL 2>&1`
</details>

####  Linux

<details>
<summary>Shell</summary>

`nohup java -Djava.util.logging.config.file=/home/agent/logging.properties -jar /home/agent/vs-agent.jar propsfile=/home/agent/client.properties >/dev/null 2>&1 &`
</details>


### Run the agent in your terminal

This can be used for testing purposes as you have the log directly printed in your terminal  
Remark: When using this command, once you close your browser, the agent stops

#### Windows

<details>
<summary>CMD</summary>

`java -Djava.util.logging.config.file="C:\Users\name\agent\logging.properties" -jar "C:\Users\name\agent\vs-agent.jar" propsfile="C:\Users\name\agent\client.properties"`
</details>

<details>
<summary>PowerShell</summary>

`java -Djava.util.logging.config.file="C:\Users\name\agent\logging.properties" -jar "C:\Users\name\agent\vs-agent.jar" propsfile="C:\Users\name\agent\client.properties"`
</details>

#### Linux

<details>
<summary>Shell</summary>

`java -Djava.util.logging.config.file=/home/agent/logging.properties -jar /home/agent/vs-agent.jar propsfile=/home/agent/client.properties`
</details>

> ℹ️ proxies
> ℹ️ 
> ℹ️ When using a proxy, add the following argument to the command: -Djava.net.useSystemProxies=true  
> ℹ️ If that does not work, you can also try to add: -Dhttps.proxyHost=<host> -Dhttps.proxyPort=<port>  
> ℹ️ Note that these properties need to be added at the start of the command, before -Djava.util.logging.config.file

## Optional

### Monitor the log files in a console

#### Windows

<details>
<summary>PowerShell</summary>

```powershell
cd C:\Users\name\agent\log
Get-Content vs-java-client-0.log -Tail 100 -Wait
```
</details>

#### Linux

<details>
<summary>Shell</summary>

```shell
cd /home/agent/log
tail -f vs-java-client-0.log
```
</details>

> ℹ️ How to know if the agent is running
> ℹ️ 
> ℹ️ If you see "No task queued" in the logs, that means that it is working correctly and polling the task queue.  You can also use the Ping Agents button on the Agent menu in VaultSpeed.

### Terminate the agent 

#### Windows

<details>
<summary>CMD and PowerShell</summary>

`taskkill /f /im javaw.exe`
</details>

#### Linux

<details>
<summary>Shell</summary>

list all java processes

`ps -ef | grep vs-agent.jar`

take the id of the process u want to kill (first column of the result) e.g. 7866, and execute:

`kill 7866`
</details>

---

> ❌ Running multiple agents at the same time will cause problems. If your connection strings are not defined in both their properties file, this will cause errors, and since getting the metadata and sending it to the cloud is a separate task, it might be executed on a different agent thus not delivering your metadata.