Running Panhandler

The recommended way to run Panhandler is to pull and run the docker container. For Windows users, refer to the Windows Installation installation document.

Quick Start

The following command will ensure you have the most up to date version of panhandler and will set up all the required ports and volume mounts. This command will also update existing Panhandler containers with the latest released version.

curl -s -k -L http://bit.ly/2xui5gM | bash

If you don’t trust running bit.ly links through Bash, then you can run this variant instead:

curl -s -k -L https://raw.githubusercontent.com/PaloAltoNetworks/panhandler/master/ph | bash

This command will install and or update Panhandler to the latest version using the default values.

If you need special requirements, such as custom volume mounts, non-default username and password, or non-standard ports, you set the following environment variables prior to launching the ‘curl’ command:

  • CNC_USERNAME - Set the default username to login to the application (default paloalto)
  • CNC_PASSWORD - Set the default password to login to the application (default panhandler)
  • IMAGE_TAG - Set the tag you want to download and install. Possible values: (dev, latest) (default latest)
  • DEFAULT_PORT - Set the port the application will listen on for web requests (default 8080)
  • FORCE_DEFAULT_PORT- Ensure your desired port will be used regardless of any previously set ports. Possible values are ‘true’ or ‘false’

Note

You must set ‘FORCE_DEFAULT_PORT’ to ‘false’ if you change the ‘DEFAULT_PORT’ to some value other than what was previously set!

Running the Panhandler Docker Container

If you need to manage the Panhandler container manually:

Using a standard web port

docker volume create panhandler_volume
docker run -p 8080:8080 -t -d \
    -v panhandler_volume:/home/cnc_user \
    -v "/var/run/docker.sock:/var/run/docker.sock" \
    -e CNC_USERNAME=paloalto \
    -e CNC_PASSWORD=panhandler \
    --name panhandler paloaltonetworks/panhandler

Then access the UI via http://localhost:8080

Changing the values of CNC_USERNAME and CNC_PASSWORD will set the default username and password respectively.

Using an alternate TCP port

If port 8080 is unavailable, you can switch to a different port. This example uses port 9999.

docker run -t -p 9999:8080 \
    -v panhandler_volume:/home/cnc_user \
    -v "/var/run/docker.sock:/var/run/docker.sock" \
    -e CNC_USERNAME=paloalto \
    -e CNC_PASSWORD=panhandler \
    --name panhandler paloaltonetworks/panhandler

Then access the UI via http://localhost:9999

Note

The -t option for terminal allows you to view panhandler output data in the terminal window. This is useful for determining any skillets errors that write to terminal output.

Using Panhandler with TLS

Here is a project that adds TLS to Panhandler: https://github.com/fatofthelan/SecurePanHandler

Stopping the docker container

The docker container runs in the background. You can stop the container by using its container ID.

docker ps
docker stop { CONTAINER ID }
_images/ph-docker-stop.png

Note

If you need to remove the container, enter docker rm { CONTAINER ID } with CONTAINER ID as the ID used to stop. You must stop the container before deleting.

Building Panhandler

If you want to build panhandler from source (which is not recommended). You will need to update the git submodules, install the pip python requirements for both the app and also CNC, create the local db, and create a local user.

git clone https://github.com/PaloAltoNetworks/panhandler.git
cd panhandler
git submodule init
git submodule update
pip install -r requirements.txt
./cnc/manage.py migrate
./cnc/manage.py shell -c "from django.contrib.auth.models import User; User.objects.create_superuser('paloalto', 'admin@example.com', 'panhandler')"

Running Panhandler manually

To start the application on your local machine on port 80:

cd panhandler/cnc
celery -A pan_cnc worker --loglevel=info &
manage.py runserver 80

To use a different port, supply a different argument to the runserver command above. In this case, the server will start up on port 80. Browse to http://localhost in a web browser to begin. The default login credentials are ‘paloalto’ and ‘panhandler’

Requirements

Panhandler has been tested to work on Docker version: 18.09.1 (Mac) and 18.09.0 (Linux). Windows Installation users are encouraged to use WSL2.

Please ensure you have the latest docker version installed for the best results.

Windows Installation

Running panhandler on Windows is possible through docker. The most reliable setup method at this time is to run docker commands directly through PowerShell backed by WSL 2. This process will require multiple reboots so plan accordingly. Other installation methods may not provide appropriate access to the docker daemon from the running panhandler container resulting in certain skillet types not functioning.

Install WSL 2

Begin by installing WSL 2. Microsoft has good documentation on how to do this here:

https://docs.microsoft.com/en-us/windows/wsl/install-win10

If unsure about a Linux distribution to use, choose the latest Ubuntu. Verify you can access WSL 2 before continuing.

Install Docker Desktop

After WSL 2 functionality is verified, install the latest Docker Desktop for Windows using the following tutorial from docker.

https://docs.docker.com/docker-for-windows/install/

During the install, ensure the following settings:
  • Use the WSL2 based engine, using “Hyper-V” may lead to some known problems
  • Start Docker Desktop when you login, it will allow panhandler to auto start on boot
  • DO NOT select “Expose daemon on tcp://localhost:2375 without TLS”
  • DO NOT select “Enable experimental features”
  • DO NOT enable “Kubernetes”

Unless the installer states otherwise, these settings can be updated by right clicking the docker icon in your system tray in the bottom right of your Windows screen and selecting “Settings”.

Although WSL 2 is required for operation, you will not be using WSL 2 to talk to docker. Open PowerShell and type “docker ps” to verify your docker cli is working and able to talk to the docker daemon. You should see output similar to this with no errors. This has to be working before you can proceed.

_images/ph-windows-1.png

Another good test to perform to ensure docker is running fine is to run the docker “Hello world” image. From PowerShell type this command:

docker run --rm -it hello-world

You should get an output similar to this:

_images/ph-windows-2.png

Install Panhandler

At this point, you are ready to install and start panhandler. In PowerShell, issue this command to pull down the latest panhandler image.

docker pull paloaltonetworks/panhandler:latest

This will take a minute, but you should get output similar to this:

_images/ph-windows-3.png

With the image downloaded, all that’s left to do is create the volumes and start panhandler. Docker volumes are virtual storage entities that provides a way to upgrade the image without losing app data. Create the volumes by running these commands:

docker volume create CNC_VOLUME
docker volume create PANHANDLER_VOLUME

You can verify the volumes have been created by running this command and checking the output matches to the image below:

docker volume list
_images/ph-windows-4.png

Now you can start panhandler by coping this entire command block into PowerShell. This command sets a restart policy of always, which ensures panhandler will restart with your computer and always run unless you stop it.

docker run `
    --name panhandler `
    -v //var/run/docker.sock:/var/run/docker.sock `
    -v PANHANDLER_VOLUME:/home/cnc_user `
    -v CNC_VOLUME:/home/cnc_user/.pan_cnc `
    -d -p 8080:8080 `
    --restart=always `
    paloaltonetworks/panhandler:latest

That command will result in a long hash that will serve as the ID for the container, but you can still reference it with the name “panhandler”.

_images/ph-windows-5.png

After a few seconds, you should be able to access panhandler in your web browser by browsing to:

http://localhost:8080/

The installation process is now complete.

Stopping and Starting Panhandler

If you wish to stop panhandler from running until you restart it, you can do so with the PowerShell command:

docker stop panhandler

Likewise, this process can be restarted with the command:

docker start panhandler

Upgrading Panhandler

Only one more command is required to upgrade panhandler. The process is to delete the old container, update the image, and start a new container.

You can delete the old container, running or stopped, with this command:

docker container rm panhandler -f
_images/ph-windows-6.png

You then can use the ‘docker pull’ and ‘docker run’ commands exactly as they are above to download a newer panhandler image and start it. The volumes you created earlier will be still be available and assigned to the new container if you use the commands as they are.

Troubleshooting Windows Install

If you run into either of the following errors when trying to install a Linux distribution:

Installing, this may take a few minutes… WslRegisterDistribution failed with error: 0x80370102 Error: 0x80370102 The virtual machine could not be started because a required feature is not installed.

or when trying to run the Docker Desktop GUI:

Hardware assisted virtualization and data execution protection must be enabled in BIOS.

After verifying that virtualization is enabled in BIOS by opening Task Manager > Performance > Virtualization, please attempt the following steps.

  1. If the Windows’ Hyper-V feature is totally disabled or not installed, enable Hyper-V by opening the PowerShell as administrator and running the following command:
dism.exe /Online /Enable-Feature:Microsoft-Hyper-V /All
  1. If the Windows’ Hyper-Vfeature is enabled and not working, enable Hypervisor with the following command and restart your system:
bcdedit /set hypervisorlaunchtype auto
  1. If the problem persists probably Hyper-V on your system is corrupted, so turn off all Hyper-V related Windows’ features under Control Panel > Programs > Windows Features. Restart your system and attempt to enable Hyper-V again.

This troubleshooting guide was found from:

Switching between Latest and Develop Containers

PanHandler runs in a Docker container, the main build tagged as ‘latest’.

There is also a develop branch with new features and updates. Although not the recommended release, some users may want to work with develop and explore new features. Some skillets being developed may also be dependent on newer features.

Updating the Running Latest Version

This script will install or update to the latest ‘dev’ image for Panhandler. This is recommended for developers or power-users who understand this code may be unstable and not all features may work all the time.

curl -s -k -L http://bit.ly/34kXVEn  | bash

The following bash script can be copy-pasted into the terminal to stop the PanHandler process, pull the latest, and run again. The example uses port 9999 for web access.

export PANHANDLER_IMAGE=paloaltonetworks/panhandler
export PANHANDLER_ID=$(docker ps | grep $PANHANDLER_IMAGE | awk '{ print $1 }')
docker stop $PANHANDLER_ID
docker rm -f $PANHANDLER_ID
docker pull $PANHANDLER_IMAGE
docker run -t -p 9999:80 -t -v $HOME/.pan_cnc:/home/cnc_user/.pan_cnc $PANHANDLER_IMAGE

Updating the Running Develop Version

The following bash script can be copy-pasted into the terminal to stop the PanHandler process, pull the develop version, and run again. The example uses port 9999 for web access.

export PANHANDLER_IMAGE=paloaltonetworks/panhandler:dev
export PANHANDLER_ID=$(docker ps | grep $PANHANDLER_IMAGE | awk '{ print $1 }')
docker stop $PANHANDLER_ID
docker rm -f $PANHANDLER_ID
docker pull $PANHANDLER_IMAGE
docker run -t -p 9999:80 -t -v $HOME/.pan_cnc:/home/cnc_user/.pan_cnc $PANHANDLER_IMAGE_D

Switching from Latest to Develop

These commands still stop the latest main release version then pull down and run the latest develop version. The latest release container will be deleted.

export PANHANDLER_IMAGE_M=paloaltonetworks/panhandler
export PANHANDLER_IMAGE_D=paloaltonetworks/panhandler:dev
export PANHANDLER_ID=$(docker ps | grep $PANHANDLER_IMAGE_M | awk '{ print $1 }')
docker stop $PANHANDLER_ID
docker rm -f $PANHANDLER_ID
docker pull $PANHANDLER_IMAGE_D
docker run -t -p 9999:80 -t -v $HOME/.pan_cnc:/home/cnc_user/.pan_cnc $PANHANDLER_IMAGE_D

Switching from Develop to Latest

These commands still stop the develop version then pull down and run the latest main release version. The develop version container will be deleted.

export PANHANDLER_IMAGE_M=paloaltonetworks/panhandler
export PANHANDLER_IMAGE_D=paloaltonetworks/panhandler:dev
export PANHANDLER_ID=$(docker ps | grep $PANHANDLER_IMAGE_D | awk '{ print $1 }')
docker stop $PANHANDLER_ID
docker rm -f $PANHANDLER_ID
docker pull $PANHANDLER_IMAGE_M
docker run -t -p 9999:80 -t -v $HOME/.pan_cnc:/home/cnc_user/.pan_cnc $PANHANDLER_IMAGE_M

When switching between dev and latest clear the cache with the following link:

http://localhost:9999/clear_cache

Keeping Up to Date

As panhandler is a quickly evolving project with new features added frequently, it is advisable to ensure you update to the latest periodically.

Update Script

The following script is useful to update your version of Panhandler to the latest while retaining all your settings, port mappings, etc.

curl -s -k -L http://bit.ly/2xui5gM | bash

This script will pull down a bash script that will determine if your version of Panhandler is the latest. If not, it will pull the latest image from Docker Hub, remove the old container and create a new container with the same port mapping as the previous version.

Note

If you are upgrading from a very old Panhandler version, you may need to import Skillet repositories again.

Manually updating the Panhandler Container

Panhandler is primarily distributed as a docker image on Docker Hub. To ensure you have the latest version, check for new releases here. To manually launch a newer version via docker:

docker pull paloaltonetworks/panhandler:latest
docker run -p 8080:8080 -t -v $HOME:/home/cnc_user paloaltonetworks/panhandler

This will create a container based on the latest image tag. Versioned panhandler images are also available and can be found on Docker Hub.

Note

You must periodically pull new images from Docker hub to ensure you have the latest software with new features and bug fixes.

To ensure you have the most up to date software, perform a docker pull and specify your desired release tag.

export TAG=latest
docker pull paloaltonetworks/panhandler:$TAG
docker run -p 8080:8080 -t -v $HOME:/home/cnc_user paloaltonetworks/panhandler:$TAG

Ensuring your Panhandler container is using the latest image

If you already have Panhandler running, you may need to use the following commands to first stop the existing container. Note the image tag in the PANHANDLER_IMAGE variable below. You may want to change this to ‘latest’ or some other specific release tag like ‘2.2’

export PANHANDLER_IMAGE=paloaltonetworks/panhandler:dev
export PANHANDLER_ID=$(docker ps | grep $PANHANDLER_IMAGE | awk '{ print $1 }')
docker stop $PANHANDLER_ID
docker rm -f $PANHANDLER_ID
docker pull $PANHANDLER_IMAGE
docker run -p 8080:8080 -t -v $HOME:/home/cnc_user -d $PANHANDLER_IMAGE

Cleaning up old versions

Once you update to a newer version of Panhandler, the older images can still be left around, taking up space on your hard drive. A common best practice is to occasionally remove old images with the following docker command:

docker image prune

Note

This command may take some time to complete, up to several minutes. The longer it takes, the more space it’s saving on your hard drive!

On my system, this command can regularly reclaim over 10GB of space.

Another good command to occasionally run is:

docker container prune

This will remove all stopped containers and recover their used disk space as well.