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
You can upload these properties via the /1.0/kb/tenants/uploadPerTenantConfig
endpoint, e.g.:
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, the per-tenant configuration takes 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
)