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
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]