Overview
Kill Bill configuration is done via several means:
Per-tenant, subsystem specific, configuration file (such as Catalog or Overdue XML configuration files, or Invoice and Payment properties).
The
killbill.properties
file, properties global to the system (specified via the Java System Property-Dorg.killbill.server.properties=file:///path/to/killbill.properties
).Java System Properties (rare cases).
Third Party configuration files (e.g. EhCache configuration file, location specified via the Java System Property
org.killbill.cache.config.location
).
Properties and their defaults are defined in the Java linked below. In these files, the value of the annotation @Config
is the configuration key to use in the killbill.properties
file or in the per-tenant configuration JSON. The default value is specified by the annotation @Default
.
You do not have to modify these Java files to change the properties values.
For example:
@Config("org.killbill.invoice.enabled")
@Default("true")
@Description("Whether the invoicing system is enabled")
boolean isInvoicingSystemEnabled();
The configuration key
org.killbill.invoice.enabled
controls whether the invoicing system is enabledThe default value is
true
Kill Bill, at runtime, can look up the property value via the method call
isInvoicingSystemEnabled()
Per tenant properties
Some of our configuration properties can be specified at the tenant level, i.e they can differ for each tenant that specified its own properties. Such properties will have an InternalTenantContext
in the signature of the method. Example:
@Config("org.killbill.invoice.sanitySafetyBoundEnabled")
@Default("true")
@Description("Whether internal sanity checks to prevent mis- and double-billing are enabled")
boolean isSanitySafetyBoundEnabled(@Param("dummy") final InternalTenantContext tenantContext);
The following configuration files have some per-tenant properties:
You can upload these properties via the /1.0/kb/tenants/uploadPerTenantConfig
endpoint, and each call should contain the full list of properties for a given tenant, i.e doing a subsequent call would overwrite previous properties. For instance to change the invoice dryRun notification schedule for the tenant boblazar
, one could use the following cURL:
curl -v \
-X POST \
-u 'admin:password' \
-H "X-Killbill-ApiKey: bob" \
-H "X-Killbill-ApiSecret: lazar" \
-H "Content-Type: text/plain" \
-H "X-Killbill-CreatedBy: configurator" \
-d '{"org.killbill.invoice.dryRunNotificationSchedule":"48h"}' \
"http://127.0.0.1:8080/1.0/kb/tenants/uploadPerTenantConfig"
You can also specify these values in your main killbill.properties
file (used as a fallback, but the per-tenant configuration would take precedence).
Global properties
Kill Bill core services can be configured through properties defined in the following classes (specify custom values in your killbill.properties
file):
Catalog configuration: used to specify the location of the default catalog if no per-tenant catalog has been uploaded
Overdue configuration: used to specify the location of the default overdue configuration if no per-tenant configuration has been uploaded
OSGI related configuration - Kill Bill will look for ruby based OSGI related properties at the location specified by
org.killbill.billing.osgi.bundles.jruby.conf.dir
in the main killbill.properties file. This is usually in/var/lib/killbill/config
so that configuration can be saved when plugins are removed or upgraded.
The properties to configure the database are split between the core Kill Bill services and the plugins, to allow plugins to use a different database or configuration:
The properties to configure the persistent buses and notification queue are shown below. Those properties are built to be used across multiple instances (we have two persistent buses) which explains the substitution parameter instanceName
.
Docker
Most config properties should be specified in the killbill.properties
file, located at /var/lib/killbill/killbill.properties
.
You can either bind mount your own file, by specifying -v /path/to/killbill.properties:/var/lib/killbill/killbill.properties
when starting your container, or specifying individual environment variables (e.g. -e KILLBILL_SERVER_TEST_MODE=false
):
KILLBILL_ANALYTICS_NOTIFICATION_NB_THREADS
(default5
)KILLBILL_ANALYTICS_QUEUE_CAPACITY
(default30000
)KILLBILL_BUNDLE_CACHE_NAME
(defaultosgi-cache
)KILLBILL_BUNDLE_INSTALL_DIR
(default/var/lib/killbill/bundles
)KILLBILL_BUNDLE_PROPERTY_NAME
(defaultkillbill.properties
)KILLBILL_BUS_EXTERNAL_HISTORY_TABLE_NAME
(defaultbus_ext_events_history
)KILLBILL_BUS_EXTERNAL_IN_MEMORY
(defaulttrue
)KILLBILL_BUS_EXTERNAL_NB_THREADS
(default50
)KILLBILL_BUS_EXTERNAL_SLEEP
(default0
)KILLBILL_BUS_EXTERNAL_TABLE_NAME
(defaultbus_ext_events
)KILLBILL_BUS_EXTERNAL_USE_INFLIGHT_Q
(defaulttrue
)KILLBILL_BUS_MAIN_CLAIMED
(default10
)KILLBILL_BUS_MAIN_HISTORY_TABLE_NAME
(defaultbus_events_history
)KILLBILL_BUS_MAIN_IN_MEMORY
(defaultfalse
)KILLBILL_BUS_MAIN_NB_THREADS
(default50
)KILLBILL_BUS_MAIN_OFF
(defaultfalse
)KILLBILL_BUS_MAIN_SLEEP
(default0
)KILLBILL_BUS_MAIN_TABLE_NAME
(defaultbus_events
)KILLBILL_CACHE_CONFIG_LOCATION
(defaultehcache.xml
)KILLBILL_CATALOG_BUNDLE_PATH
(defaultorg/killbill/billing/util/template/translation/CatalogTranslation
)KILLBILL_CATALOG_URI
(defaultSpyCarBasic.xml
)KILLBILL_CURRENCY_PROVIDER_DEFAULT
(defaultkillbill-currency-plugin
)KILLBILL_DAO_CACHE_PREP_STMTS
(defaulttrue
)KILLBILL_DAO_CONNECTION_TIMEOUT
(default100s
)KILLBILL_DAO_HEALTH_CHECK_CONNECTION_TIMEOUT
(default10s
)KILLBILL_DAO_HEALTH_CHECK_EXPECTED99TH_PERCENTILE
(default50ms
)KILLBILL_DAO_IDLE_CONNECTION_TEST_PERIOD
(default5m
)KILLBILL_DAO_IDLE_MAX_AGE
(default2m
)KILLBILL_DAO_LOG_LEVEL
(defaultDEBUG
)KILLBILL_DAO_MAX_ACTIVE
(default150
)KILLBILL_DAO_MAX_CONNECTION_AGE
(default0m
)KILLBILL_DAO_MIN_IDLE
(default5
)KILLBILL_DAO_MYSQL_SERVER_VERSION
(default4.0
)KILLBILL_DAO_PASSWORD
(defaultkillkill
)KILLBILL_DAO_POOLING_TYPE
(defaultHIKARICP
)KILLBILL_DAO_PREP_STMT_CACHE_SIZE
(default500
)KILLBILL_DAO_PREP_STMT_CACHE_SQL_LIMIT
(default2048
)KILLBILL_DAO_URL
(defaultjdbc:h2:file:/var/lib/killbill/killbill;MODE=MYSQL;DB_CLOSE_DELAY=-1;MVCC=true;DB_CLOSE_ON_EXIT=FALSE
)KILLBILL_DAO_USER
(defaultkillbill
)KILLBILL_DAO_USE_SERVER_PREP_STMTS
(defaulttrue
)KILLBILL_DEFAULT_LOCALE
(defaulten_US
)KILLBILL_EXPORT_PACKAGES_API
(defaultorg.killbill.billing.account.api,org.killbill.billing.analytics.api.sanity,org.killbill.billing.analytics.api.user,org.killbill.billing.beatrix.bus.api,org.killbill.billing.catalog.api,org.killbill.billing.catalog.api.rules,org.killbill.billing.invoice.plugin.api,org.killbill.billing.invoice.api,org.killbill.billing.invoice.api.formatters,org.killbill.billing.entitlement.api,org.killbill.billing,org.killbill.clock,org.killbill.billing.notification.api,org.killbill.billing.notification.plugin.api,org.killbill.billing.notification.plugin,org.killbill.billing.osgi.api,org.killbill.billing.osgi.api.config,org.killbill.billing.overdue,org.killbill.billing.payment.api,org.killbill.billing.payment.plugin.api,org.killbill.billing.control.plugin.api,org.killbill.billing.tenant.api,org.killbill.billing.usage.api,org.killbill.billing.util.api,org.killbill.billing.util.nodes,org.killbill.billing.util.audit,org.killbill.billing.util.callcontext,org.killbill.billing.util.customfield,org.killbill.billing.util.email,org.killbill.billing.util.entity,org.killbill.billing.util.tag,org.killbill.billing.util.template,org.killbill.billing.util.template.translation,org.killbill.billing.currency.plugin.api,org.killbill.billing.catalog.plugin.api,org.killbill.billing.entitlement.plugin.api,org.killbill.billing.currency.api,org.killbill.billing.security.api,org.killbill.billing.osgi.libs.killbill,org.joda.time;org.joda.time.format;version=2.9,org.slf4j;version=1.7.2,org.osgi.service.log;version=1.3,org.osgi.service.http;version=1.2.0,org.osgi.service.deploymentadmin;version=1.1.0,org.osgi.service.event;version=1.2.0
)KILLBILL_EXPORT_PACKAGES_EXTRA
(default ``)KILLBILL_EXPORT_PACKAGES_JAVA
(defaultcom.sun.xml.internal.ws,com.sun.xml.internal.ws.addressing,com.sun.xml.internal.ws.addressing.model,com.sun.xml.internal.ws.addressing.policy,com.sun.xml.internal.ws.addressing.v200408,com.sun.xml.internal.ws.api,com.sun.xml.internal.ws.api.addressing,com.sun.xml.internal.ws.api.client,com.sun.xml.internal.ws.api.config.management,com.sun.xml.internal.ws.api.config.management.policy,com.sun.xml.internal.ws.api.fastinfoset,com.sun.xml.internal.ws.api.ha,com.sun.xml.internal.ws.api.handler,com.sun.xml.internal.ws.api.message,com.sun.xml.internal.ws.api.message.stream,com.sun.xml.internal.ws.api.model,com.sun.xml.internal.ws.api.model.soap,com.sun.xml.internal.ws.api.model.wsdl,com.sun.xml.internal.ws.api.pipe,com.sun.xml.internal.ws.api.pipe.helper,com.sun.xml.internal.ws.api.policy,com.sun.xml.internal.ws.api.server,com.sun.xml.internal.ws.api.streaming,com.sun.xml.internal.ws.api.wsdl.parser,com.sun.xml.internal.ws.api.wsdl.writer,com.sun.xml.internal.ws.binding,com.sun.xml.internal.ws.client,com.sun.xml.internal.ws.client.dispatch,com.sun.xml.internal.ws.client.sei,com.sun.xml.internal.ws.config.management.policy,com.sun.xml.internal.ws.developer,com.sun.xml.internal.ws.encoding,com.sun.xml.internal.ws.encoding.fastinfoset,com.sun.xml.internal.ws.encoding.policy,com.sun.xml.internal.ws.encoding.soap,com.sun.xml.internal.ws.encoding.soap.streaming,com.sun.xml.internal.ws.encoding.xml,com.sun.xml.internal.ws.fault,com.sun.xml.internal.ws.handler,com.sun.xml.internal.ws.message,com.sun.xml.internal.ws.message.jaxb,com.sun.xml.internal.ws.message.saaj,com.sun.xml.internal.ws.message.source,com.sun.xml.internal.ws.message.stream,com.sun.xml.internal.ws.model,com.sun.xml.internal.ws.model.soap,com.sun.xml.internal.ws.model.wsdl,com.sun.xml.internal.ws.org.objectweb.asm,com.sun.xml.internal.ws.policy,com.sun.xml.internal.ws.policy.jaxws,com.sun.xml.internal.ws.policy.jaxws.spi,com.sun.xml.internal.ws.policy.privateutil,com.sun.xml.internal.ws.policy.sourcemodel,com.sun.xml.internal.ws.policy.sourcemodel.attach,com.sun.xml.internal.ws.policy.sourcemodel.wspolicy,com.sun.xml.internal.ws.policy.spi,com.sun.xml.internal.ws.policy.subject,com.sun.xml.internal.ws.protocol.soap,com.sun.xml.internal.ws.protocol.xml,com.sun.xml.internal.ws.resources,com.sun.xml.internal.ws.server,com.sun.xml.internal.ws.server.provider,com.sun.xml.internal.ws.server.sei,com.sun.xml.internal.ws.spi,com.sun.xml.internal.ws.streaming,com.sun.xml.internal.ws.transport,com.sun.xml.internal.ws.transport.http,com.sun.xml.internal.ws.transport.http.client,com.sun.xml.internal.ws.transport.http.server,com.sun.xml.internal.ws.util,com.sun.xml.internal.ws.util.exception,com.sun.xml.internal.ws.util.localization,com.sun.xml.internal.ws.util.pipe,com.sun.xml.internal.ws.util.xml,com.sun.xml.internal.ws.wsdl,com.sun.xml.internal.ws.wsdl.parser,com.sun.xml.internal.ws.wsdl.writer,com.sun.xml.internal.ws.wsdl.writer.document,com.sun.xml.internal.ws.wsdl.writer.document.http,com.sun.xml.internal.ws.wsdl.writer.document.soap,com.sun.xml.internal.ws.wsdl.writer.document.soap12,com.sun.xml.internal.ws.wsdl.writer.document.xsd,javax.annotation,javax.management,javax.naming,javax.naming.ldap,javax.net,javax.net.ssl,javax.crypto,javax.crypto.spec,javax.sql,javax.sql.rowset,javax.sql.rowset.serial,javax.transaction,javax.transaction.xa,javax.xml,javax.xml.bind,javax.xml.validation,javax.xml.namespace,javax.xml.parsers,javax.xml.validation,javax.xml.stream,javax.xml.stream.events,javax.xml.stream.util,javax.xml.transform,javax.xml.transform.dom,javax.xml.transform.sax,javax.xml.transform.stax,javax.xml.transform.stream,javax.xml.xpath,javax.jws.soap,com.sun.org,com.sun.org.apache,com.sun.org.apache.xml,com.sun.org.apache.xml.internal,com.sun.org.apache.xml.internal.utils,com.sun.org.apache.xpath,com.sun.org.apache.xpath.internal,com.sun.org.apache.xpath.internal.jaxp,com.sun.org.apache.xpath.internal.objects,org.w3c.dom,org.w3c.dom.bootstrap,org.w3c.dom.events,org.w3c.dom.ls,org.w3c.dom.css,org.w3c.dom.html,org.w3c.dom.ranges,org.w3c.dom.stylesheets,org.w3c.dom.traversal,org.w3c.dom.views,org.xml.sax,org.xml.sax.ext,org.xml.sax.helpers,sun.misc,sun.misc.unsafe,sun.security,sun.security.util,javax.servlet;version=3.1,javax.servlet.http;version=3.1
)KILLBILL_EXTERNAL_CLAIM_TIME
(default5m
)KILLBILL_EXTERNAL_INFLIGHT_CLAIMED
(default500
)KILLBILL_EXTERNAL_QUEUE_CAPACITY
(default1000000
)KILLBILL_FAILURE_RETRY_MULTIPLIER
(default2
)KILLBILL_INVOICE_DRY_RUN_NOTIFICATION_SCHEDULE
(default0s
)KILLBILL_INVOICE_ENABLED
(defaulttrue
)KILLBILL_INVOICE_GLOBAL_LOCK_RETRIES
(default50
)KILLBILL_INVOICE_MAX_DAILY_NUMBER_OF_ITEMS_SAFETY_BOUND
(default15
)KILLBILL_INVOICE_MAX_NUMBER_OF_MONTHS_IN_FUTURE
(default36
)KILLBILL_INVOICE_READ_MAX_RAW_USAGE_PREVIOUS_PERIOD
(default2
)KILLBILL_INVOICE_SANITY_SAFETY_BOUND_ENABLED
(defaulttrue
)KILLBILL_JANITOR_ATTEMPTS_DELAY
(default12h
)KILLBILL_JANITOR_PENDING_RETRIES
(default65m,3h,3h,5h,1d,1d,1d,1d
)KILLBILL_JANITOR_UNKNOWN_RETRIES
(default1h,6h,17h
)KILLBILL_JAXRS_LOCATION_HOST
(default ``)KILLBILL_JAXRS_LOCATION_USE_FORWARD_HEADERS
(defaulttrue
)KILLBILL_JAXRS_TIMEOUT
(default30s
)KILLBILL_JRUBY_CONF_DIR
(default/var/lib/killbill/config
)KILLBILL_JRUBY_CONTEXT_SCOPE
(defaultTHREADSAFE
)KILLBILL_LOCATION_FULL_URL
(defaulttrue
)KILLBILL_MAIN_CLAIM_TIME
(default5m
)KILLBILL_MAIN_NOTIFICATION_NB_THREADS
(default10
)KILLBILL_MAIN_NOTIFICATION_OFF
(defaultfalse
)KILLBILL_MAIN_QUEUE_CAPACITY
(default1000000
)KILLBILL_MAIN_QUEUE_CAPACITY
(default100
)KILLBILL_MAIN_QUEUE_MODE
(defaultSTICKY_POLLING
)KILLBILL_MANUAL_PAY_TEMPLATE_NAME
(defaultorg/killbill/billing/util/email/templates/HtmlInvoiceTemplate.mustache
)KILLBILL_MAX_FAILURE_RETRY
(default3
)KILLBILL_METRICS_GRAPHITE_HOST
(defaultlocalhost
)KILLBILL_METRICS_GRAPHITE_INTERVAL
(default30
)KILLBILL_METRICS_GRAPHITE_PORT
(default2003
)KILLBILL_METRICS_GRAPHITE_PREFIX
(defaultkillbill
)KILLBILL_METRICS_GRAPHITE
(defaultfalse
)KILLBILL_METRICS_INFLUXDB_DATABASE
(default30
)KILLBILL_METRICS_INFLUXDB_HOST
(defaultlocalhost
)KILLBILL_METRICS_INFLUXDB_INTERVAL
(default30
)KILLBILL_METRICS_INFLUXDB_PORT
(default2003
)KILLBILL_METRICS_INFLUXDB_PREFIX
(defaultkillbill
)KILLBILL_METRICS_INFLUXDB_SENDER_TYPE
(defaultkillbill
)KILLBILL_METRICS_INFLUXDB_SOCKET_TIMEOUT
(default30
)KILLBILL_METRICS_INFLUXDB
(defaultfalse
)KILLBILL_NOTIFICATIONQ_ANALYTICS_CLAIMED
(default100
)KILLBILL_NOTIFICATIONQ_ANALYTICS_HISTORY_TABLE_NAME
(defaultanalytics_notifications_history
)KILLBILL_NOTIFICATIONQ_ANALYTICS_IN_MEMORY
(defaultfalse
)KILLBILL_NOTIFICATIONQ_ANALYTICS_SLEEP
(default3000
)KILLBILL_NOTIFICATIONQ_ANALYTICS_TABLE_NAME
(defaultanalytics_notifications
)KILLBILL_NOTIFICATIONQ_MAIN_CLAIMED
(default100
)KILLBILL_NOTIFICATIONQ_MAIN_HISTORY_TABLE_NAME
(defaultnotifications_history
)KILLBILL_NOTIFICATIONQ_MAIN_IN_MEMORY
(defaultfalse
)KILLBILL_NOTIFICATIONQ_MAIN_SLEEP
(default70000
)KILLBILL_NOTIFICATIONQ_MAIN_TABLE_NAME
(defaultnotifications
)KILLBILL_OSGI_DAO_CACHE_PREP_STMTS
(defaulttrue
)KILLBILL_OSGI_DAO_CONNECTION_TIMEOUT
(default100s
)KILLBILL_OSGI_DAO_IDLE_CONNECTION_TEST_PERIOD
(default5m
)KILLBILL_OSGI_DAO_IDLE_MAX_AGE
(default2m
)KILLBILL_OSGI_DAO_LOG_LEVEL
(defaultDEBUG
)KILLBILL_OSGI_DAO_MAX_ACTIVE
(default150
)KILLBILL_OSGI_DAO_MAX_CONNECTION_AGE
(default0m
)KILLBILL_OSGI_DAO_MIN_IDLE
(default5
)KILLBILL_OSGI_DAO_MYSQL_SERVER_VERSION
(default4.0
)KILLBILL_OSGI_DAO_PASSWORD
(defaultkillbill
)KILLBILL_OSGI_DAO_POOLING_TYPE
(defaultHIKARICP
)KILLBILL_OSGI_DAO_PREP_STMT_CACHE_SIZE
(default500
)KILLBILL_OSGI_DAO_PREP_STMT_CACHE_SQL_LIMIT
(default2048
)KILLBILL_OSGI_DAO_URL
(defaultjdbc:h2:file:/var/lib/killbill/killbill;MODE=MYSQL;DB_CLOSE_DELAY=-1;MVCC=true;DB_CLOSE_ON_EXIT=FALSE
)KILLBILL_OSGI_DAO_USER
(defaultkillbill
)KILLBILL_OSGI_DAO_USE_SERVER_PREP_STMTS
(defaulttrue
)KILLBILL_OSGI_ROOT_DIR
(default/var/tmp/felix
)KILLBILL_OVERDUE_URI
(defaultNoOverdueConfig.xml
)KILLBILL_PAYMENT_GLOBAL_LOCK_RETRIES
(default50
)KILLBILL_PAYMENT_INVOICE_PLUGIN
(default ``)KILLBILL_PAYMENT_JANITOR_RATE
(default5m
)KILLBILL_PAYMENT_PLUGIN_TIMEOUT
(default64s
)KILLBILL_PAYMENT_PROVIDER_DEFAULT
(defaultEXTERNAL_PAYMENT
)KILLBILL_PAYMENT_RETRY_DAYS
(default8,8,8
)KILLBILL_PLUGIN_THREADS_NB
(default100
)KILLBILL_RBAC_GLOBAL_SESSION_TIMEOUT
(default1h
)KILLBILL_RETRY_MAX_ATTEMPTS
(default8
)KILLBILL_RETRY_START_SEC
(default300
)KILLBILL_SECURITY_SHIRO_NB_HASH_ITERATIONS
(default200000
)KILLBILL_SECURITY_SHIRO_RESOURCE_PATH
(defaultclasspath:shiro.ini
)KILLBILL_SERVER_BASE_URL
(defaulthttp://127.0.0.1:8080
)KILLBILL_SERVER_HTTP_GZIP
(defaultfalse
)KILLBILL_SERVER_MULTITENANT
(defaulttrue
)KILLBILL_SERVER_NOTIFICATIONS_RETRIES
(default15m,30m,2h,12h,1d
)KILLBILL_SERVER_REGION
(defaultlocal
)KILLBILL_SERVER_SHUTDOWN_DELAY
(default0s
)KILLBILL_SERVER_TEST_MODE
(defaulttrue
)KILLBILL_TEMPLATE_BUNDLE_PATH
(defaultorg/killbill/billing/util/template/translation/InvoiceTranslation
)KILLBILL_TEMPLATE_INVOICE_FORMATTER_FACTORY_CLASS
(defaultorg.killbill.billing.invoice.template.formatters.DefaultInvoiceFormatterFactory
)KILLBILL_TEMPLATE_NAME
(defaultorg/killbill/billing/util/email/templates/HtmlInvoiceTemplate.mustache
)KILLBILL_TENANT_BROADCAST_RATE
(default5s
)KILLBILL_THREADS_POOL_NB
(default30
)KILLBILL_UTIL_BROADCAST_RATE
(default5s
)