Installing PO Box to a Virtual Machine

Owned by Marco Palella (Unlicensed)
Last updated: Aug 12, 2024 by Mike (Bin) Li
5 min read

This guide outlines the requirements to install PO Box onto a Docker container. We assume that you have basic knowledge of Linux Commands in this document. We also address the differences in setup for running the container on Windows

Requirements

Zilla PO Box can be installed on a Linux machine that can support hosting a Docker container. The machine running this container must also be unix-based. We recommend using an ubuntu or debian image to host this.

At this time, We can only support one instance of PO Box per Zilla tenant

Prerequisites

You will need to do the following before deploying the container.

  1. Install the most recent stable version of Docker onto the device. Please visit Docker’s website for more info on how to install Docker.

  2. The Docker container will also be deployed by using a compose file to instruct the configuration this will require docker compose or docker-compose to be available.

Note: availability and installation of `docker compose` may vary by OS

  1. The configuration provided in installation requires User ID 1000 and Group ID 1000 to perform the following
    sudo mkdir /opt/zilla && sudo chown 1000:1000 /opt/zilla && sudo chmod 700 /opt/zilla && mkdir /opt/zilla/zinc-config /opt/zilla/zinc-output

Alternatively the docker-compose.yaml can be modified to use alternate directories.

  1. The user running installation will also need to be part of the docker group: sudo usermod -aG docker $USER
    The above command may vary depending on system OS and configuration.

  2. Ensure that outbound connections via port 443 are allowed. Bare minimum, Zilla will need outbound connections allowed to:

Region

Hosts

Region

Hosts

Americas and Canada (Production)

app.zillasecurity.com/*

Americas and Canada (Dev/Sandboxes)

qa.zsec.io/*

Europe and UK

eu.zillasecurity.com/*

Asia Pacific and Australia

anz.zillasecurity.com/*

UK

uk.zillasecurity.com/*

  1. email support@zillasecurity.com and request a PO Box API Token, along with the link to download the PO Box image and the Docker Yaml file that will be needed for installation

 

Installation

  1. Login to your Linux instance

  2. Create a directory called po-box somewhere on your system hosting PO Box. On linux, you can use the command mkdir /home/$USER/po-box

  3. Download the PO Box image and the docker YAML file to the directory using the links provided by Zilla Support. You can use the command curl -O {URL} to download the files once you have the URLs

  4. Create 2 directories that will be mounted to the container: zinc-config (stores all the config data to connect to systems) and zinc-output (temporarily stores outputs from systems so they can be sent to Zilla). If you are putting this on a linux system, store these at /opt/zilla/zilla-config and /opt/zilla/zilla-output. The following command will create these directories and give the proper access to the service user PO-Box is using:

sudo mkdir /opt/zilla && sudo chown 1000:1000 /opt/zilla && sudo chmod 700 /opt/zilla && mkdir /opt/zilla/zinc-config /opt/zilla/zinc-output

  1. Create a file in the directory zilla-config called Zilla_API_Key. This is where the API Key we are using to connect to the Zilla Mothership will be stored. This will be provided to you by Zilla support. On Linux, you can run the following to create the file:

cat > /opt/zilla/zinc-config/Zilla_API_Key

  1. Next, open the Zilla_API_Key file with an editing tool like nano, vim, or vscode. Copy the API Token given to you by support and paste it into the Zilla_API_Key file you created. The API Key should have the following structure in the file:

{"access_token": "token string", "refresh_token": "token string"}

  1. Navigate back to the po-box directory and load the image using this command:

This will load the Zilla image onto Docker. You can check to make sure this was successful by running the below command and ensuring the PO Box image is now appearing:

  1. Next, open the docker-compose.yml file with Nano or VScode. This is the file that stores global configuration parameters for the container. In this file, you will need to add your tenant domain to the variable TENANT_DOMAIN. This is the domain corresponding to your Zilla tenant. You can find this inside of the global settings of your Zilla tenant. It will be the first domain listed under Your Domains. In the screenshot below, my tenant domain would be mp.access-ventures.com

image-20240416-160838.png

You will also need to update the image parameter to match the image that you loaded. To get this value, run sudo docker image ls on terminal. You should see something like this:

 

image-20240417-162713.png

Take the REPOSITORY Value and the TAG Value, then concatenate them together with a colon in between. This is the value you will add to the image variable in the docker-compose.yml file. As an example, for the image in the screenshot above, the image value would be the following:

  1. If you did not use the default folder names for zinc-config and zinc-output, you will also need to adjust these 2 parameters in the YAML file as well:

You will also need to change the volume parameter to be the new filepath. As an example, if you decided to put zinc-output and zinc-config inside of the path /home/zilla-security instead of /opt/zilla, then you will need to change the volume parameter in the config from:

to be:

  1. Once you have made these edits, save the YAML file

  2. compose and run the docker container by running the following command in the po-box folder:

  1. Confirm with your technical resource or support@zillasecurity.com to ensure that the container is successfully calling home to Zilla.

Next Steps

Once PO Box is installed, you can move onto configuring service accounts on the systems that you are going to be pulling user information for. Please see Creating Service Accounts For PO Box for more info.