Local Configuration | Honeycomb

We use cookies or similar technologies to personalize your online experience & tailor marketing to you. Many of our product features require cookies to function properly.

Read our privacy policy I accept cookies from this site

Local Configuration

Secure Tenancy is planned to be End-of-Life at the end of 2022 in favor of built-in security enhancements. Existing customers using Secure Tenancy will continue to be supported on Honeycomb Classic until this time.

Setting Up Secure Tenancy 

The Honeycomb team will provide you with either a system package, such as a DEB or RPM, or a .tar.gz containing the elements required to run the Secure Proxy.

If we provide a full package, you may not need to create some of the files or directories mentioned here manually, but rather edit their values.

Install Release Package 

  1. The default location for the install is /srv/hny.
  2. The default location for configuration is /srv/hny/config/.

If you choose to install elsewhere, you must specify the location of the configuration file as a command line argument (-hnyconfig flag) to the binary.

mkdir -p /srv/hny
cd /srv/hny
<place file from above step in this directory>
tar --strip-components 1 -xjf <provided_tarball>


Generate Your Authentication Token 

Your authentication token is sensitive information and should not be shared outside of the operator(s) of the Secure Proxy.

Run this command to generate a long random hexadecimal token:

head -c64 /dev/urandom | openssl dgst -sha256 -hex | sed -e 's/(stdin)= //'

If you use a secret management tool, such as Vault, and wish to keep this secret there, use a # to comment out the auth_token line in the configuration file below, and instead set the HONEYCOMB_AUTH_TOKEN environment variable to the correct value when the proxy is started. Environment variables override the values from the configuration file, so if both are set, the values from the environment will be used.

Set Up Your Configuration File 

Add the token from the step above to /srv/hny/config/honeycomb.yml. The value must be in quotes.

/srv/hny/config/honeycomb.yml is also the file used for other configuration values, like GRPC and HSTS.

# ---- auth_token -----
# This token is sent to Honeycomb with each ingest API request.  If it does not match the value on the
# ingest side (configurable in your team settings on https://ui.honeycomb.io/)
# the request will be rejected.
auth_token: ... # CHANGE ME (hex string, max 255 characters, for example "0123456789abcdef0123456789abcdef")
# ---- Proxy Metrics setup (optional, but recommended ----
# See documentation for info on finding this parameter.
libhoney_writekey: ... # CHANGE ME <copy parameter from team API key, per doc>
# ---- GRPC (optional) -----
# Address for honeycomb to ingest grpc data. If GRPC is used, this value is required,
# including the port.
# api_grpc_base_url: https://api.honeycomb.io:443
# Address on which the proxy should listen for grpc requests.
# Defaults to all interfaces
# grpc_listen_addr: :8081
# ---- HSTS (optional) -----
# Enable HTTP Strict Transport Security (HSTS)
# (https://en.wikipedia.org/wiki/HTTP_Strict_Transport_Security)
# http_strict_transport_security_enabled: false
# The maximum time (in seconds) that client browsers should cache the HSTS configuration.
# Must be an integer greater than 0.
# http_strict_transport_security_max_age: 600
# ---- Use behind proxies (optional) -----
# CORS: normally, the Honeycomb client expects to be talking to the honeycomb UI at
# https://ui.honeycomb.io
# This can be overridden in the case of a proxy by uncommenting the line below and
# changing the destination URL:
# ui_base_url: https://ui.honeycomb.io
# Client requests must pass CORS. The default behavior is to return the
# "Access-Control-Allow-Origin" header with the value from ui_base_url above.
# If your client requests does not appear to originate from that address,
# you can specify one or more allowed_origins by uncommenting the lines below.
# One of these must exactly match the Origin header to be returned; wildcards
# are not supported.
# allowed_origins:
#     - https://proxy1.myserver.com
#     - https://proxy2.myserver.com
# If your hostnames are dynamically assigned and match a pattern, or you would
# like to use wildcards, you can also specify a list of regular expressions in
# allowed_origin_patterns.  For example the following would extend the 2 line
# example above to match many proxy hosts matching a pattern, as well as another
# set of origins matching a different pattern:
# allowed_origin_patterns:
#     - ^https:\/\/proxy[0-9]+\.myserver\.com$
#     - ^https:\/\/internal-proxy[0-9]+\.myserver\.com$
# NOTE: make sure to put the ^ and $ at the beginning and end of the expression, as
# leaving either off will open the door to matching any hostname containing the
# pattern.
# Some browser requests to the Secure Tenancy service are returned with a redirect
# which is normally directed to the ui_base_url. However, if the proxy used by
# the ST service is not the same as the proxy used by the browser, this redirect
# might fail, so you can specify a different address by uncommenting below.
# redirect_url: https://browserproxy.mysite.com
# ---- Hashing (optional) ----
# Uncomment this line to use hashing instead of encryption. Note that doing so will
# significantly increase the minimum required size and performance of your SQL database.
# See docs for more info.
# transformer: sha256hmac
# The Secure Tenancy service uses parallel tasks (known as goroutines)
# to process encryption requests. This sets the maximum number of such tasks;
# the default is 8. A system under heavy load, particularly one with many CPU
# cores, may wish to increase this value; depending on load, values as high as
# 100 are not unreasonable. The honeycomb field to watch is transform_req_chan_len;
# tune it to be more than 0 under heavy load but less than max_parallelism.
# max_parallelism=8

Configure Database 

Secure Tenancy requires a database, and can use either MySQL or Postgres. Instructions are provided below for both; use the appropriate instructions for your configuration.


After installing MySQL on the database server, create or edit /srv/hny/config/sql.yml to include the following fields, so it is able to connect to the MySQL instance:

user: root
password: ""
host: localhost:3306
database: honeycomb_secure_proxy
maxopenconns: 100

For legacy reasons, /srv/hny/config/mysql.yml is also supported as a filename.

Use this command to create the MySQL database:

mysql -u root -e 'create database honeycomb_secure_proxy;'

Run the database migrations to populate the database schemas:

cd /srv/hny && \
bin/migrate -url "mysql://<user>:<password>@tcp(<host>:<port>)/honeycomb_secure_proxy" -path ./migrate/mysql up

If Secure Proxy is connecting to MySQL over TLS, set the tls key. The following values are supported:

  • false: disables TLS (default)
  • true: enables TLS, uses the hostname portion of host for ServerName
  • skip-verify: enables TLS, does not verify ServerName matches the cert
  • Any other value uses the specified value as ServerName (even if it does not match the hostname portion of host)

To specify a non-default location for the MySQL configuration file, use the -mysqlconfig flag.


After installing Postgres on the database server, use this command on that server to create the Postgres database:

  psql -U root -h localhost -c "CREATE DATABASE honeycomb_secure_proxy"

Create or edit /srv/hny/config/sql.yml to include the following fields, so it is able to connect to the Postgres instance:

sqlprovider: postgres
user: root
password: "password"
host: localhost:5432
database: honeycomb_secure_proxy
maxopenconns: 100

Apply the database migrations to populate the database schemas:

cd /srv/hny && \
bin/migrate4 -provider=postgres -database "honeycomb_secure_proxy" -path=./migrate/postgres up

If Secure Proxy is connecting to Postgres over TLS, set the tls key. The following values for the tls key are supported:

  • false: disables TLS (default)
  • true: enables TLS, uses the hostname portion of host for ServerName
  • skip-verify: enables TLS, does not verify ServerName matches the cert
  • Any other value uses the specified value as the Postgres sslmode parameter

To specify a non-default location for the database configuration file, use the -sqlconfig flag.

Additional keys supported in sql.yml (for Postgres only) include:

  • sslcert: a path to a certificate file
  • ssl_min_protocol_version: minimum TLS version allowed
  • ssl_max_protocol_version: maximum TLS version allowed

See Postgres documentation for detailed information on the proper use of these parameters.

Lock Down Proxy/Database 

Do a pre-flight check to ensure that the Secure Proxy installation and the MySQL database are not accessible from outside the private network(s) they are installed in. The database contains the keys used to encrypt and decrypt information sent to Honeycomb. Be sure to secure the database from untrusted access.

Send Proxy Metrics to Honeycomb 

This step is optional, but recommended.

You can help Honeycomb ensure the quality of our service by sending usage and debugging information from the Secure Proxy to Honeycomb. This data does not contain any sensitive information, and is available to access in your own Honeycomb account.

To enable sending proxy metrics, you must create a new team that is not in high security mode. Log into Honeycomb and go to the Teams page. On that page, use Create Team with a new name for the team.

After creating this new team, set the libhoney_writekey parameter in /srv/hny/config/honeycomb.yml with the team’s API key, which is found on the Account page.

Then, let your Honeycomb representative know about the team name. This team for telemetry information is still under your control, and you can delete the dataset at any time you choose.

Create a System Service 

For systemd, create the following file: /lib/systemd/system/honeycomb_secure_proxy.service

Edit the file to include the following:

Description=Honeycomb Secure Proxy


Alias=honeycomb_secure_proxy honeycomb_secure_proxy.service

Reload the systemd process:

sudo systemctl daemon-reload

Start the system service:

sudo systemctl start honeycomb_secure_proxy

Enable the service to start on boot:

sudo systemctl enable honeycomb_secure_proxy

By default, the Secure Proxy will run on port 8080.

Configure TLS Termination 

When you have deployed the Secure Proxy, configure TLS termination on the load balancer that fronts the proxy instances. If HTTP/HTTPS content is mixed, the Honeycomb browser UI will not load.

Continue on Honeycomb 

Now continue your setup.

Did you find what you were looking for?