Startup configuration

Introduction

This page describes Vinyl's startup configuration parameters and methods. Each section is the top-level schema for the JSON form (appsettings.json) configuration method.

When Vinyl starts, it gets its configuration values from any of the following sources, in order of precedence:

1. System environment variables.
2. An ASP.NET Core appsettings.json JSON file.
3. (Vinyl 3.0 and earlier) A connection.xml XML file with a <ConnectionInfo> element.

System environment variables are the JSON schemas, sub-schemas (if any), and keys separated by two underscore characters. There is no default appsettings.json file. You can create one in the installation directory using the samples in C:\inetpub\wwwroot\Vinyl\ (Windows) or the samples sub-directory (Linux), many of which are reproduced on this page.

As an example, the following configuration methods provide equivalent values:

Environment variables

ConnectionInfo__DatabaseType=SQLServer
ConnectionInfo__HostName=localhost
ConnectionInfo__DatabaseName=Vinyl
ConnectionInfo__UserName=vinyl
ConnectionInfo__Password=P@5$w0rD

appsettings.json file

{
  "ConnectionInfo": {
    "DatabaseType": "SQLServer",
    "HostName": "localhost",
    "DatabaseName": "Vinyl",
    "UserName": "vinyl",
    "Password": "P@5$w0rD"
  }
}

connection.xml file

<ConnectionInfo DatabaseType="MySQL" HostName="localhost" DatabaseName="Vinyl" UserName="vinyl" Password="P@5$w0rD"/>

BackgroundService

Schema	Key	Value Type	Description
BackgroundService	DisableScheduler	Boolean	Set to true to disable the background services scheduler.

Examples

JSON

{
  "BackgroundService": {
    "DisableScheduler": true
  }
}

Environment variable

BackgroundService__DisableScheduler=true

ConnectionInfo

Schema	Key	Value Type	Description
ConnectionInfo	DatabaseType	String	Database type: SQLServer, MySQL, PostgreSql
	HostName	String	Database server host name or IP address.
	Port	Integer	Database server port number.
	InstanceName	String	Database server instance name.
	TenantName	String	For internal use.
	DatabaseName	String	Vinyl database name.
	UserName	String	Vinyl database username.
	Password	String	Vinyl database password.
	ConnectionTimeout	Integer	Database connection timeout (seconds).
	CommandTimeout	Integer	Database command timeout (seconds).
	MaxPoolSize	Integer	Maximum number of Database connections in the pool.
	Advanced	Object array	Additional connection string key/value pairs.

Examples

{
  "ConnectionInfo": {
    "DatabaseType": "SQLServer",
    "HostName": "localhost",
    "DatabaseName": "Vinyl",
    "UserName": "Vinyl",
    "Password": "password",
    "Advanced": "MultiSubnetFailover=true;TrustServerCertificate=true;"
  }
}

DataEncryption

The DataEncryption section configures Data Encryption Key (DEK) storage and encryption.

Schema	Key	Value Type	Description
DataEncryption	Certificate	String	Base64-encoded, PKCS#12 (PFX) X.509 certificate.
	CertificatePassword	String	X.509 certificate password.
	CertificateThumbprint	String	X.509 certificate thumbprint.
	Directory	String	File system directory path.
	Import	String	Storage and encryption policies for importing DEKs.
	KeyEncryption	String	Data encryption strategy: Certificate: X.509 certificate encryption policy. Kms: AWS KMS key encryption policy. None: No key encryption policy. Keys are stored in plain text. Null: Passthrough key encryption policy. Keys are stored in plain text.
	KeyStorage	String	Data encryption key storage location: Database: Vinyl database. FileSystem: File system. ParameterStore: AWS System Manager Parameter Store. S3: S3 bucket.
	KmsKeyId	String	AWS KMS key ARN.
	ParameterNamePrefix	String	AWS System Manager Parameter Store parameter name prefix.
	S3BucketEndpoint	String	S3 bucket endpoint.
	S3KeyPrefix	String	S3 key prefix.

Examples

{
  "DataEncryption": {
    "KeyEncryption": "Certificate",
    "CertificateThumbprint": "a909502dd82ae41433e6f83886b00d4277a32a7b",
    "Certificate": "{base64-pfx-data}",
    "CertificatePassword": "your-certificate-password"
  }
}

{
  "DataEncryption": {
    "KeyEncryption": "Kms",
    "KmsKeyId": "{kms-key-arn}"
  }
}

{
  "DataEncryption": {
    "KeyEncryption": "None"
  }
}

{
  "DataEncryption": {
    "KeyEncryption": "Null"
  }
}

{
  "DataEncryption": {
    "KeyStorage": "Database"
  }
}

{
  "DataEncryption": {
    "KeyStorage": "FileSystem",
    "Directory": "C:\\Path\\To\\Keys"
  }
}

{
  "DataEncryption": {
    "KeyStorage": "ParameterStore",
    "ParameterNamePrefix": "/production"
  }
}

{
  "DataEncryption": {
    "KeyStorage": "S3",
    "S3BucketEndpoint": "https://{bucket}.s3{-aws-region}.amazonaws.com",
    "S3KeyPrefix": "production"
  }
}

Kestrel

The Kestrel section configures the Kestrel web server.

Schema	Key	Value Type	Description
Kestrel	Limits	MaxRequestBodySize	See the Kestrel documentation for a list of supported options.

License

The License section specifies the Vinyl license key.

Schema	Key	Value Type	Description
License	LicenseKey	String	A base64-encoded version of your vinyl.lic file.

Examples

{
  "License": {
    "LicenseKey": "TWF1cmlzIGFjIGZlbGlzIHZlbCB2ZWxpdCB0cmlzdGlxdWUgaW1wZXJkaWV0LiAgTnVsbGFtIGV1IGFudGUgdmVsIGVzdCBjb252YWxsaXMgZGlnbmlzc2ltLiAgRnVzY2Ugc3VzY2lwaXQsIHdpc2kgbmVjIGZhY2lsaXNpcyBmYWNpbGlzaXMsIGVzdCBkdWkgZmVybWVudHVtIGxlbywgcXVpcyB0ZW1wb3IgbGlndWxhIGVyYXQgcXVpcyBvZGlvLiAgTnVuYyBwb3J0YSB2dWxwdXRhdGUgdGVsbHVzLiAgTnVuYyBydXRydW0gdHVycGlzIHNlZCBwZWRlLiAgU2VkIGJpYmVuZHVtLiAgQWxpcXVhbSBwb3N1ZXJlLiAgTnVuYyBhbGlxdWV0LCBhdWd1ZSBuZWMgYWRpcGlzY2luZyBpbnRlcmR1bSwgbGFjdXMgdGVsbHVzIG1hbGVzdWFkYSBtYXNzYSwgcXVpcyB2YXJpdXMgbWkgcHVydXMgbm9uIG9kaW8uICBQZWxsZW50ZXNxdWUgY29uZGltZW50dW0sIG1hZ25hIHV0IHN1c2NpcGl0IGhlbmRyZXJpdCwgaXBzdW0gYXVndWUgb3JuYXJlIG51bGxhLCBub24gbHVjdHVzIGRpYW0gbmVxdWUgc2l0IGFtZXQgdXJuYS4gIEN1cmFiaXR1ciB2dWxwdXRhdGUgdmVzdGlidWx1bSBsb3JlbS4gIEZ1c2NlIHNhZ2l0dGlzLCBsaWJlcm8gbm9uIG1vbGVzdGllIG1vbGxpcywgbWFnbmEgb3JjaSB1bHRyaWNlcyBkb2xvciwgYXQgdnVscHV0YXRlIG5lcXVlIG51bGxhIGxhY2luaWEgZXJvcy4gIFNlZCBpZCBsaWd1bGEgcXVpcyBlc3QgY29udmFsbGlzIHRlbXBvci4gIEN1cmFiaXR1ciBsYWNpbmlhIHB1bHZpbmFyIG5pYmguICBOYW0gYSBzYXBpZW4uCg=="
  }
}

PostgreSQL

Schema	Key	Value Type	Description
PostgreSQL	Logging
	OpenTelemetry

ReverseProxy

The ReverseProxy section configures a reverse proxy.

Schema	Key	Value Type	Description
ReverseProxy	ForwardedClientIpHeader	String	HTTP header that forwards the original client IP address.
	ForwardedSchemeHeader	String	HTTP header that forwards the original scheme.
	ForwardedHostHeader	String	HTTP header that forwards the original host and optional port. Since Vinyl 3.3.34291.
	ForwardedPortHeader	String	HTTP header that forwards the original port.

Examples

{
  "ReverseProxy": {
    "ForwardedClientIpHeader": "X-Forwarded-For",
    "ForwardedSchemeHeader": "X-Forwarded-Proto",
    "ForwardedHostHeader": "X-Forwarded-Host"
  }
}

{
  "ReverseProxy": {
    "ForwardedClientIpHeader": "X-Forwarded-For",
    "ForwardedSchemeHeader": "X-Forwarded-Proto",
    "ForwardedPortHeader": "X-Forwarded-Port"
  }
}

Security

The Security section configures Vinyl user accounts and security providers.

Schema	Key	Value Type	Description
Security	Administrator	Schema	Admin account options.
	InvitationUrl	String	For internal use.
	LocalAuthentication	Schema	Local user security provider options.
	Provider	String	Base64-encoded security provider configuration.
	Providers	String array	base64-encoded security provider configuration.
	AuthenticationExpiry	Integer	Authentication token expiration, in minutes. Since Vinyl 3.3.34291.

Schema	Key	Value Type	Description
Administrator	AllowLocalAuthentication	Boolean	Enables local user authentication.
	ChangePasswordOnLogin	Boolean	Forces user to change password on login.
	DefaultPassword	String	Default password. Applied once on installation.
	Password	String	Password. Applied each time the system starts.

Schema	Key	Value Type	Description
LocalAuthentication	Enabled	Boolean	Enables the security provider.
	ShowOnLoginForm	Boolean	Determines if the user authentication provider appears on the login form.

Examples

{
  "Security": {
    "Administrator": {
      "Password": "s3cr3t",
      "ChangePasswordOnLogin": false
    },
    "LocalAuthentication": {
      "ShowOnLoginForm": false
    },
    "Provider": "Tm90aGluZyBjYW4gY29tZSBvZiBub3RoaW5nLCBzcGVhayBhZ2Fpbi4="
  }
}

Scripting

The Scripting section configures Vinyl's C# scripting SDK.

Schema	Key	Value Type	Description
Scripting	Enabled	Boolean	Enables C# scripting.

Examples

{
  "Scripting": {
    "Enabled": false
  }
}

SharedState

The SharedState section configures the shared-state service which supports multi-server deployments.

Schema	Key	Value Type	Description
SharedState	Provider	String	Shared state provider: InProcess: State is stored in-process for single-server deployments. Redis: State is stored in Redis for multi-server deployments.
	RedisConnectionString	String	Redis connection string.
	RedisPrefix	String	Redis key prefix.

Example

{
  "SharedState": {
    "Provider": "Redis",
    "RedisConnectionString": "localhost:6379"
  }
}

SignalR

The SignalR section configures client-server communications.

Schema	Key	Value Type	Description
SignalR	LongPollingTimeout	String	Long polling timeout, specified using a TimeSpan format. Example: 00:00:30.
	Transports	String	Comma-delimited list of HTTP transport types: LongPolling: Long-polling. None: No transports. NOT SUPPORTED. ServerSentEvents: Server-sent events. WebSockets: WebSockets .

Examples

{
  "SignalR": {
    "Transports": "WebSockets,LongPolling",
    "LongPollingTimeout": "00:00:30"
  }
}

Site

The Site section configures the Vinyl website address and known aliases.

Schema	Key	Value Type	Description
Site	Url	String	Canonical web site URL.
	Default	Boolean	Treat as the default web site.
	Redirect	Boolean	Redirect clients to the site URL.
	RedirectIfHeaderExists	String	HTTP header that indicates clients should be redirected.
	AllowCrossOrigin	Boolean	Allow cross-origin requests.
	Aliases	String array	Site aliases.

Examples

{
  "Site": {
    "Url": "https://example.com/Vinyl",
    "Default": true,
    "Redirect": true,
    "RedirectIfHeaderExists": "X-Forwarded-For",
    "Aliases": [
      {
        "Url": "https://vinyl.example.com"
      }
    ]
  }
}

Sku

Schema	Key	Value Type	Description
Sku	Sku	String

Tls

The Tls section configures TLS protocol support.

Schema	Key	Value Type	Description
Tls	SecurityProtocol	String	Comma-delimited list of security protocols: Ssl3: SSL 3.0 SystemDefault: System default protocol support. Tls: TLS 1.0 Tls11: TLS 1.1 Tls12: TLS 1.2 Tls13: TLS 1.3

Examples

{
  "Tls": {
    "SecurityProtocol": "Tls,Tls11,Tls12"
  }
}

UrlRewrite

The UrlRewrite section configures URL rewriting support.

Schema	Key	Value Type	Description
UrlRewrite	OriginalUrlHeader	String	HTTP header that forwards the original URL.

Examples

{
  "UrlRewrite": {
    "OriginalUrlHeader": "X-Original-URL"
  }
}