0 0 Share PDF

How do I upload my UCP license with the Docker API?

Article ID: KB000760


It may be useful to supply a license to UCP via the API, such as for automating a test environment or for troubleshooting.


These instructions apply to versions of the API used in UCP 2.1.x and UCP 2.2.x. In both cases, have your docker_subscription.lic file handy.

  • For UCP 2.1.x, it's extremely helpful to have the jq binary installed on your workstation.

  • For UCP 2.2.x, you should be running Docker engine 17.06, which supports docker configs.


For UCP 2.1.x

  1. Obtain an authorization token from the Docker API:

    token=$(curl -sSkL "https://ucp.example.com/auth/login" -X POST -d '{"username":admin,"password":"password"}' | jq -r .auth_token)
  2. Next, submit your authorization token & license via the API:

    curl -SskL "https://ucp.example.com/api/config/license" -X POST -H "Authorization: Bearer ${token}" -d "{\"auto_refresh\":true,\"license_config\":$(cat ${license_file} | jq .)}"

    If your shell session is local to the swarm, such as when you are sshed to a manager node, you may substitute the manager's hostname for the UCP external URL.

For UCP 2.2.x and UCP 3.0.x

  1. Determine the name of the current UCP license config object, and set a variable NEXT_LICENSE_NAME to a name for the new object:

    CURRENT_LICENSE_NAME=$(docker service inspect ucp-agent --format '{{range .Spec.TaskTemplate.ContainerSpec.Configs}}{{if eq "/etc/ucp/docker.lic" .File.Name}}{{.ConfigName}}{{end}}{{end}}')
    if [ -z $CURRENT_LICENSE_NAME ]; then
  2. Create a new config object using NEXT_LICENSE_NAME:

    docker config create ${NEXT_LICENSE_NAME}  docker_subscription.lic
  3. Update the ucp-agent service with the new config:

    docker service update ucp-agent --config-rm "${CURRENT_LICENSE_NAME}" --config-add source="${NEXT_LICENSE_NAME}",target=/etc/ucp/docker.lic

What's Next

  • jq manipulates json, and is very helpful in interacting with the Docker API

  • More information about the UCP API can be found at docs.docker.com

  • Store configuration data in Docker Swarm at docs.docker.com

  • UCP configuration with docker configs at docs.docker.com