Site Tab Certificates Tab Headers Tab DNS Challenge Tab API Challenge Tab Proxy Tab
CapeSoft Logo

CapeSoft NetTalk
Web Server Run Time Settings

Download Latest Version
Installed Version Latest Version

NetTalk WebServer Run Time Settings

Site Tab

Secure Port

This is the port number that the server will listen on for secure traffic. This is usually set to port 443, but can be any port number. If the site is not secure then you can set this field to 0. If this is set to 0 then the Insecure port number should be set, but all the settings on the Certificates tab can be blank.

If the command line switch secureport=number is used, then the server will use this setting. For example secureport=443 . If the command line is used then the option on the window will be disabled.

Insecure Port

This is the insecure port number. Any incoming traffic on this port will be redirected to the secure port. This is usually port 80. If the server is secure, and there is another server on this machine already listening on port 80 then you should leave this setting at 0.

To get automatic certificates using the LetsEncrypt HTTP Challenge, this port MUST be 80, or another server on the server MUST be listening on port 80.

If the command line switch insecureport=number is used, then the server will use this setting. For example insecureport=80 . If the command line is used then the option on the window will be disabled.

Family

Determines if this server is listening on IPv4 addresses, or IPv6 addresses.

One server instance can only listen to one family (IPv4 or IPv6, but not both), however multiple instances of the same Exe (with the same settings) can be run on the same computer at the same time, using the command line switches /IPv4 and /IPv6.  If the command line switch is used, then this radio option will be disabled.

Bind to IP Address

Servers can have multiple local IP Addresses. If you want to limit this server to only serve on a single IP address then enter it here. This address can be in IPv4 or IPv6 format. If this field is set then the Family will be taken from this field, and the Family setting will be disabled.

This setting can be set from the command line using the switch bind=address. For example bind=192.168.2.11 or bind=::1 .

This Field must contain a valid IPv4 address, or a valid IPv6 address, or be blank.

Web Folder

The location of the Web folder on the disk. This folder holds the static files, like CSS and JS files.

For security reasons the only static files that the server can serve must be located in the Web Folder (or a sub folder of the web folder).

Session Timeout

Each user who connects to the server starts a session. This setting sets the length of the session timeout. If no activity happens on a session (in other words the user does nothing), for this amount of time, then the session is marked for deletion. Note that deletion is not immediate - other factors come into play for when a session is actually deleted.

Default Theme

The default CSS theme for the site. If this is changed then all existing sessions will be set to the new theme (which will then take effect on the next page refresh.) Note that users who have custom themes set will also see this change, so if you allow custom themes on a user level then be careful when you change this setting.

Max Threads

The maximum number of requests that the server will serve simultaneously before generating a HTTP 503 Server Busy error.

The best number to put in here depends completely on your program, and the machine you are running on. Typically setting this value to 100 is a good default. On servers with large numbers of cores, and if each thread does not consume too much RAM, then this number can be higher.

Certificates Tab

Testing Checkbox

If this checkbox is on then certificates will be retrieved from the LetsEncrypt testing server. It is recommended that this option is on until all the certificates have been successfully retrieved. The LetsEncrypt production server is rate-limited, meaning that if you make some mistakes setting it up, you could exceed the rate limit and have to wait several days or so to try again. By setting it up using the testing server you can get all the settings correct, then switch to the production server.

The testing server certificates are untrusted. This means if they are in use, and you access the site with a browser you will get a scary warning. You can proceed for testing. Once you have completed testing, untick the testing checkbox and click the Certificates button. This will retrieve certificates from the LetsEncrypt production server.

Check / Get Certificates Button

Click on this button to see the dates for the existing certificates. If no certificates exist, or the certificates have less than 30 days before expiry, then new certificates will be fetched.

The Testing option above determines if the certificates come from the Test server or the Production server.

Restart Server Button

When settings material to the Server itself change, then the server has to be restarted. This is done automatically when necessary. However you can force a server restart with this button.

Challenge Method

Choose between HTTP, DNS and API. The default is HTTP. For more information on Challenge Methods see Lets Encrypt DNS Challenge and Getting Certificates via an API.

Certificates Folder

This is the location of the certificate (.crt and .key) files. By default this is the \certificates folder under the exe. You can set the full path to anywhere on the disk where you would like the certificates to be stored. Make sure the program has write-access to the folder.

Acme Web Folder

This is the location, of the web folder, for whatever server is listening on port 80 on this machine. In order for LetsEncrypt to work there must be a web server listening on port 80 on this machine, either this server (see Insecure Port above) or some other server.
If this server is listening on port 80, then set this to the Web Folder for this server. If it's some other server then set it to the web folder (ie root folder) of the other server.

CA Account

Some unique name to identify this server with LetsEncrypt. Your business name, or generic site name will do fine. For example we use CapeSoftCA.

Ciphers Allowed

The underlying encryption engine is complicated, and supports many different encryption ciphers. When a client connects to the server they negotiate a cipher to use. Generally speaking the cipher list is a balance between allowing older clients (who don't know the new ciphers) to connect, and requiring strong ciphers for all users. Next to the Ciphers Allowed field are two buttons, one labelled "D' for Default and the other "S" for "Maximum Security". The actual values under these buttons may change in the future.

Currently the Default cipher list is
ECDH+AESGCM:ECDH+CHACHA20:DH+AESGCM:ECDH+AES256:DH+AES256:ECDH+AES128:DH+AES:RSA+AESGCM:RSA+AES:!aNU
while the Secure one is more restricted to
DHE-RSA-AES256-GCM-SHA384:DHE-RSA-AES128-GCM-SHA256:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-RSA-AES128-GCM

By exposing this field at run time (from NetTalk 14) it allows the value to be changed in the future, without recompiling the program, if it is necessary to do so. If this field is set incorrectly then TLS connections to the server will fail. Use of the D or S buttons is recommended. The D button populates the Default list, and the S button populates the more Secure, but more restricted, list. If this field is left blank then the NetTalk internal default list will be used.

Domains

A list of domains that are pointing at this server. For example capesoft.com and capesoft.com are served by the same server. This list of domains allows one server to serve pages for more than one domain.

Domains with no extension, or one of the local extensions, will also get certificates generated - although not from LetsEncrypt. Self-Signed certificates for these domains will be generated, and placed in the certificates folder.

A local extension is a domain that ends with one of the following; .local, .intranet, .internal, .private, .corp, .home, .lan and .test .
If the domain is a numeric IPv4 or IPv6 address, then it is also considered to be local, and a self-signed certificate is issued.

Certificate Password(s)

Certificates make use of CRT and KEY files. KEY files are generated by NetTalk. CRT files are generated by the Certificate Authority.

It's possible to store the KEY files on the disk, in an encrypted form. This prevents the KEY files being removed, and used to generate more certificates, which could then be used in MITM attacks. This setting allows you to set passwords for the domains.

This field is a Comma-Separated-list of passwords. The order of the passwords matches the order of the domains. One password for each domain. If there are fewer passwords than domains, then the extra domains will have no password applied to the KEY file.

If you get a certificate from an alternate source, and it has a password, then simply put that password into the list here.

Note that changing the password, or removing it, will render existing keys (that don't use that password) inoperative.

Log

The Log text box can be used to observe the certificate process, and to assist in debugging if the server fails to get the certificates.

Trace

If this option is on then communications to the LetsEncrypt server will also be sent to DebugView. This allows for a more detailed inspection of the communications for cases when it does not work, to get clues as to why it failed.

Headers Tab

These security headers are included in the HTTP header sent back to the client. The client may, or may not, respect these headers. Typically settings these headers makes your site more secure, but at the same time may restrict use in specific situations.

DNS Challenge Tab

For more on the use of DNS Challenges to get certificates, see LetsEncrypt DNS Challenge.

DNSService Provider

Choose from one of the supported DNS providers. The Program Developer will need to have signed up an account with this provider, and registered a domain there. The domain is entered as the root domain below.

User ID

The User ID for the login to the DNS Service Provider.

Password

The password of the DNS Service Provider.

Account ID

The Account ID at the DNS Service Provider. A lookup button exists so this value can be fetched from the DNS Provider.

Root Domain

The domain registered at the DNS Provider.

Test DNS Credentials button

Click this button to see if the DNS Credentials have been entered correctly.

API Challenge Tab

This tab is only applicable if the challenge type is set to API. This type requires that you set up a DNS API Web Server for your product. This server is deployed on the internet somewhere, and all your product deployments, at your customers, talk to this server to get certificates.

For more on API Challenges see Getting a Certificate via an API.

API Server URL

This is the URL to your DNS API server

User ID

This is a User ID, as configured at your DNS API Server

Password

This is the password for that user.

Proxy Tab

If you are doing LetsEncrypt HTTP challenges, then it's possible the NetAcme class (which does all the work) needs to access the internet via a proxy server. If this is the case then you can turn it on here, and enter the web-client Proxy settings that are needed.

Command Line Switches

Some of the options above can be set from the command line when the program is run.

This allows multiple instances of the server to start on the same machine, in the same folder, (thus sharing settings), while at the same time using slightly different runtime settings.

For example you may want one instance to run listing to IPv4, and another to listen on IPv6. Or you may need to run multiple instances on different port numbers.

Settings which support this option are noted in the documentation above.
[End of this document]
Return to NetTalk Documentation Index