Portal Configuration Guide
The portal configuration is much smaller than the API Server.
Note: Unlike the API server, not all configuration resides under a vinyldns
namespace.
Configuration
- Database Configuration
- LDAP
- Cryptography
- Custom Links
- Additional Configuration Settings
- Full Example Config
Database Configuration
VinylDNS supports a MySQL backend (see API Database Configuration).
Follow the MySQL Setup Guide first to get the values you need to configure here.
The Portal uses the following tables:
user
userChanges
Note that the user table is shared between the API and the portal, and must be configured with the same values in both configs:
vinyldns {
# this list should include only the datastores being used by your portal instance (user and userChange repo)
data-stores = ["mysql"]
mysql {
# this is the path to the mysql provider. This should not be edited
# from the default in reference.conf
class-name = "vinyldns.mysql.repository.MySqlDataStoreProvider"
settings {
# the name of the database, recommend to leave this as is
name = "vinyldns"
# the jdbc driver, recommended to leave this as is
driver = "org.mariadb.jdbc.Driver"
# the URL used to create the schema, typically this will be without the "database" name
migration-url = "jdbc:mariadb://localhost:19002/?user=root&password=pass"
# the main connection URL
url = "jdbc:mariadb://localhost:19002/vinyldns?user=root&password=pass"
# the user to connect to MySQL
user = "root"
# the password to connect to MySQL
password = "pass"
## see https://github.com/brettwooldridge/HikariCP for more detail on the following fields
# the maximum number of connections to scale the connection pool to
maximum-pool-size = 20
# the maximum number of milliseconds to wait for a connection from the connection pool
connection-timeout-millis = 1000
# the minimum number of idle connections that HikariCP tries to maintain in the pool
minimum-idle = 10
# the maximum number of milliseconds that a connection is can sit idle in the pool
idle-timeout = 10000
# The max lifetime of a connection in a pool. Should be several seconds shorter than the database imposed connection time limit
max-lifetime = 600000
# controls whether JMX MBeans are registered
register-mbeans = true
# my-sql-properties allows you to include any additional mysql performance settings you want.
# Note that the properties within my-sql-properties must be camel case!
# see https://github.com/brettwooldridge/HikariCP/wiki/MySQL-Configuration for guidance
my-sql-properties {
prepStmtCacheSize = 300
prepStmtCacheSqlLimit = 2048
cachePrepStmts = true
useServerPrepStmts = true
rewriteBatchedStatements = true
}
}
repositories {
# all repositories with config sections here will be enabled in mysql
user {
# no additional settings for repositories enabled in mysql
}
}
}
}
LDAP
Be sure to follow the LDAP Setup Guide first to get the values you need to configure here.
LDAP configuration connects VinylDNS to your Directory where user information is stored.
The default value for user sync enabled is false and user sync hours polling interval is 24 (max value). If the hours polling interval is configured higher than 24, 24 hours will be used.
LDAP {
# The name of the user to connect VinylDNS to LDAP
user="test"
# The password for the user to connect VinylDNS to LDAP
password="test"
# The domain for the user connecting VinylDNS to LDAP
domain="test"
# One or more search bases to find users. If users come from multiple domains, list them here
searchBase = [{organization = "someDomain", domainName = "DC=test,DC=test,DC=com"}, {organization = "anotherDomain", domainName = "DC=test,DC=com"}]
# Connection information to LDAP
context {
initialContextFactory = "com.sun.jndi.ldap.LdapCtxFactory"
securityAuthentication = "simple"
# Set this to point to your LDAP
providerUrl = "ldaps://somedomain.com:9999"
}
user-sync {
enabled = true # Default value is false
hours-polling-interval = 12 # Default value is 24
}
}
Cryptography Settings
The Portal encrypts user secrets at rest using the same mechanism as the API server.
Note: It is extremely important that these settings match the API server, otherwise the API server will not be able to decrypt user secrets and your installation will fail!
Cryptography is pluggable, meaning you can bring your own crypto with you. All that is required is to provide an
implementation of CryptoAlgebra
using a crypto library of choice. The default implementation is NoOpCrypto
, which does not do any encryption (not recommended for production).
The following are the configuration settings for crypto. Notice here the only thing we see is the type
. The type
is the fully qualified class name for the CryptoAlgebra
you will be using. If your crypto implementation requires
additional settings, they will be configured inside the crypto
element, adjacent to the type
.
crypto {
type = "vinyldns.core.crypto.JavaCrypto"
secret = "8B06A7F3BC8A2497736F1916A123AA40E88217BE9264D8872597EF7A6E5DCE61"
}
Custom Links
Custom links display either on the nav bar once logged in, or on the log in screen. These links are useful to point to internal documentation and procedures. For example, how to raise certain tickets with engineering, or internal slack channels.
# an array of links
links = [
{
# indicates that this link should be display on the sidebar once logged in
displayOnSidebar = true
# display this link also on the login screen
displayOnLoginScreen = true
# text to display for the link
title = "API Documentation"
# the hyperlink address being linked to
href = "https://vinyldns.io"
# a fa icon to display
icon = "fa fa-file-text-o"
}
]
Additional Configuration Settings
Play Secret
The play secret must be set to a secret value, and should be an environment variable
# See https://www.playframework.com/documentation/latest/ApplicationSecret for more details.
play.http.secret.key = "vinyldnsportal-change-this-for-production"
Play Allowed Hosts Filter
Play provides a filter that lets you configure which hosts can access your application. The filter introduces a whitelist of allowed hosts and sends a 400 (Bad Request) response to all requests with a host that do not match the whitelist.
# See https://www.playframework.com/documentation/2.8.x/AllowedHostsFilter for more details.
# Note: allowed = ["."] matches all hosts hence would not be recommended in a production environment.
play.filters.hosts {
allowed = ["."]
}
Test Login
The test login should not be used for production environments. It is useful to tinker with VinylDNS. If this
setting is true, then you can login with testuser
and testpassword
. Logging in using the testuser
will not
contact LDAP.
portal.test_login = false
HTTP Port
The HTTP Port that the Portal server will bind to
http.port=9001
Portal URL
Necessary to preview the metadata while sharing the portal link to social media
portal.vinyldns.url = "http://localhost:9001"
Shared Zones Display / Record Owner Selection
Necessary to enable shared zones submission and record ownership
shared-display-enabled = true
Batch Change Limit
How many changes are allowable in a single DNS change request
batch-change-limit = 1000
Manual Review Enabled
Triggers the manual review process for certain DNS requests
manual-batch-review-enabled = true
Scheduled Changes
Allows users to schedule changes to be run sometime in the future
scheduled-changes-enabled = true
Full Example Config
# This is the main configuration file for the application.
# ~~~~~
# Secret key
# ~~~~~
# The secret key is used to secure cryptographics functions.
#
# This must be changed for production, but we recommend not changing it in this file.
#
# See https://www.playframework.com/documentation/latest/ApplicationSecret for more details.
play.http.secret.key = "vinyldnsportal-change-this-for-production"
# See https://www.playframework.com/documentation/2.8.x/AllowedHostsFilter for more details.
# Note: allowed = ["."] matches all hosts hence would not be recommended in a production environment.
play.filters.hosts {
allowed = ["."]
}
# The application languages
# ~~~~~
play.i18n.langs = [ "en" ]
portal.vinyldns.backend.url = "http://vinyldns-api:9000"
portal.vinyldns.url = "http://localhost:9001"
portal.test_login = false
# configuration for the users and groups store
data-stores = ["mysql"]
mysql {
class-name = "vinyldns.mysql.repository.MySqlDataStoreProvider"
settings {
name = "vinyldns"
driver = "org.mariadb.jdbc.Driver"
migration-url = "jdbc:mariadb://localhost:19002/?user=root&password=pass"
url = "jdbc:mariadb://localhost:19002/vinyldns?user=root&password=pass"
user = "root"
password = "pass"
maximum-pool-size = 20
minimum-idle = 10
connection-timeout-millis = 1000
idle-timeout = 10000
max-lifetime = 600000
register-mbeans = true
my-sql-properties {
prepStmtCacheSize = 300
prepStmtCacheSqlLimit = 2048
cachePrepStmts = true
useServerPrepStmts = true
rewriteBatchedStatements = true
}
}
repositories {
user {
}
}
}
}
play.filters.enabled += "play.filters.csrf.CSRFFilter"
# Expire session after 10 hours
play.http.session.maxAge = 10h
# session secure should be false in order to run properly locally, this is set properly on deployment
play.http.session.secure = false
play.http.session.httpOnly = true
# use no-op by default
crypto {
type = "vinyldns.core.crypto.NoOpCrypto"
}
http.port=9001
links = [
{
displayOnSidebar = true
displayOnLoginScreen = true
title = "API Documentation"
href = "https://vinyldns.io"
icon = "fa fa-file-text-o"
}
]