Chapter 1. Using the toolbox

The 3scale toolbox is a Ruby client that lets you manage 3scale services from the command line.

1.1. Installing the toolbox

The only officially supported method of installing the toolbox is on Red Hat Enterprise Linux using yum or rpm.

You need the following prerequisites:

  • Access to the rhel-7-server-3scale-amp-2.4-rpms repository.

    Add it by running: 

    subscription-manager repos --enable=rhel-7-server-3scale-amp-2.4-rpms

  • Access to the rhel-server-rhscl-7-rpms repository.

    Add it by running: 

    sudo yum-config-manager --enable rhel-server-rhscl-7-rpms

Then install the toolbox: 

$ yum install 3scale_toolbox

You can however use unsupported versions on Fedora Linux, Ubuntu Linux, Windows and macOS by downloading and installing the .rpm, .deb, .msi or .pkg file directly from GitHub.

1.2. Importing services

Import services from a CSV file by specifying the following fields in this order (you also need to include these headers in your CSV file): 

service_name,endpoint_name,endpoint_http_method,endpoint_path,auth_mode,endpoint_system_name,type

You’ll need the following information:

  • 3scale admin account: {3SCALE_ADMIN}
  • domain your 3scale instance is running on: {DOMAIN_NAME} (if you’re using hosted APICast this is 3scale.net)
  • access key of your account: {ACCESS_KEY}
  • CSV file of services (examples/import_example.csv)

Import the services by running: 

$ 3scale import csv --destination=https://{ACCESS_KEY}@{3SCALE_ADMIN}-admin.{DOMAIN_NAME} --file=examples/import_example.csv

1.3. Copying services

Create a new service based on an existing one from the same SaaS account or from another account.

You’ll need the following information:

  • service id you want to copy: {SERVICE_ID}
  • 3scale admin account: {3SCALE_ADMIN}
  • domain your 3scale instance is running on: {DOMAIN_NAME} (if you’re using hosted APICast this is 3scale.net)
  • access key of your account: {ACCESS_KEY}
  • access key of the destination account if you’re copying to a different account: {DEST_KEY}
  • name for the new service: {NEW_NAME} 
$ 3scale copy service {SERVICE_ID} --source=https://{ACCESS_KEY}@{3SCALE_ADMIN}-admin.{DOMAIN_NAME} --destination=https://{DEST_KEY}@{3SCALE_ADMIN}-admin.{DOMAIN_NAME} --target_system_name={NEW_NAME}

1.4. Copying service settings only

Bulk copy (also known as updating) the service settings, proxy settings, metrics, methods, application plans, application plan limits and mapping rules from one service to another which already exists.

You’ll need the following information:

  • service id you want to copy: {SERVICE_ID}
  • service id of the destination: {DEST_ID}
  • 3scale admin account: {3SCALE_ADMIN}
  • domain your 3scale instance is running on: {DOMAIN_NAME} (if you’re using hosted APICast this is 3scale.net)
  • access key of your account: {ACCESS_KEY}
  • access key of the destination account: {DEST_KEY}

And can use the following optional flags:

  • -f remove existing target service mapping rules before copying
  • -r copy only mapping rules to target service 
$ 3scale update [opts] service --source=https://{ACCESS_KEY}@{3SCALE_ADMIN}-admin.{DOMAIN_NAME} --destination=https://{DEST_KEY}@{3SCALE_ADMIN}-admin.{DOMAIN_NAME} {SERVICE_ID} {DEST_ID}

1.5. Troubleshooting SSL issues

There is more information on certificates in the Red Hat documentation, but if you’re getting issues related to self-signed SSL certificates, SSL certificate problem: self signed certificate for example , you can download and use the remote certificate:

  1. Download the remote certificate using openssl 

    $ echo | openssl s_client -showcerts -servername self-signed.badssl.com -connect self-signed.badssl.com:443 2>/dev/null | sed -ne '/-BEGIN CERTIFICATE-/,/-END CERTIFICATE-/p' > self-signed-cert.pem

  2. Make sure it works by using it with curl 

    $ SSL_CERT_FILE=self-signed-cert.pem curl -v https://self-signed.badssl.com

    If the certificate is working properly, you won’t get the SSL error.

  3. Prefix your 3scale commands with SSL_CERT_FILE=self-signed-cert.pem: 

    $ SSL_CERT_FILE=self-signed-cert.pem 3scale import csv