-
Notifications
You must be signed in to change notification settings - Fork 3
Install and configure
This is the easy option for Linux users. The following command should be executed in a terminal and will install a MongoDB database and the Shelter system.
curl -L https://raw.githubusercontent.com/rafaeljusto/shelter/master/deploy/debian/install.sh | sh
You can also manually download the debian file here and install it:
sudo dpkg -i shelter_<version>_<arch>.deb
To use the repository Docker version, you can run the following commands (with docker.io installation for Ubuntu 14.04 LTS or greater).
sudo apt-get install docker.io
sudo docker.io run -d -P rafaeljusto/shelter
To retrieve the ports from the container just type the command bellow.
sudo docker.io ps
sudo docker.io inspect <instance-id>
If you want a really secure environment, compile from the source, editing before the file secret/key.go with your random bytes. This will guarantee that you passwords and secrets are encrypted using your own symmetric key.
The basic configuration file is shown bellow in Unix like version.
{
"basePath": "/usr/shelter",
"logFilename": "var/log/shelter.log",
"logLevel": "normal",
"languages": [ "en-US", "pt-BR" ],
"database": {
"name": "shelter",
"uri": "localhost:27017"
},
"scan": {
"enabled": true,
"time": "05:00:00 -0300",
"intervalHours": 24,
"numberOfQueriers": 400,
"domainsBufferSize": 100,
"errorsBufferSize": 100,
"udpMaxSize": 4096,
"saveAtOnce": 100,
"connectionRetries": 3,
"resolver": {
"address": "8.8.8.8",
"port": 53
},
"timeouts": {
"dialSeconds": 1,
"readSeconds": 1,
"writeSeconds": 1
},
"verificationIntervals": {
"maxOKDays": 7,
"maxErrorDays": 3,
"maxExpirationAlertDays": 10
}
},
"restServer": {
"enabled": true,
"languageConfigPath": "etc/messages.conf",
"tls": {
"certificatePath": "etc/keys/cert.pem",
"privateKeyPath": "etc/keys/key.pem"
},
"listeners": [
{
"ip": "0.0.0.0",
"port": 4443,
"tls": true
}
],
"timeouts": {
"readSeconds": 5,
"writeSeconds": 5
},
"acl": [ "127.0.0.0/8", "10.0.0.0/8", "172.16.0.0/12", "192.168.0.0/16" ],
"secrets": {
"key01": "ohV43/9bKlVNaXeNTqEuHQp57LCPCQ=="
}
},
"webClient": {
"enabled": true,
"staticPath": "templates/client",
"tls": {
"certificatePath": "etc/keys/cert.pem",
"privateKeyPath": "etc/keys/key.pem"
},
"listeners": [
{
"ip": "0.0.0.0",
"port": 4444,
"tls": true
}
]
},
"notification": {
"enabled": true,
"time": "07:00:00 -0300",
"intervalHours": 24,
"nameserverErrorAlertDays": 7,
"nameserverTimeoutAlertDays": 30,
"dsErrorAlertDays": 1,
"dsTimeoutAlertDays": 7,
"from": "[email protected].",
"templatesPath": "templates/notification",
"smtpServer": {
"server": "smtp.gmail.com",
"port": 587,
"auth": {
"type": "PLAIN",
"username": "user",
"password": "password"
}
}
}
}Attention: If you're developing the system, there's also the configuration files from the integration tests that are inside each integration test folder. They follow the same structure with some extra information or not (depending on the test).
Lets describe each part of the configuration file.
"basePath": "/usr/shelter",
Base path of the system, all other paths will prepend this path. This is useful to isolate the project in a specific directory.
"logFilename": "var/log/shelter.log",
Path and name of the file that will receive all the messages from the Shelter system.
"logLevel": "normal",
Define the verbosity in the log file. Possible values are: "normal", "info" and "debug".
"languages": [ "en-US", "pt-BR" ],
List of supported languages. When adding a new language, remember to respect the IANA Language Subtag Registry file to define the name (e.g. en-US, pt-BR) and to add the necessary information for the new language (REST messages, notification template and web client languages).
Stores the database information to start a connection. For now we are using MongoDB for the persistence layer.
"name": "shelter",
Name of the database.
"uri": "localhost:27017"
URI used by MongoDB to connect to the database.
"enabled": true,
Flag to enable or disable the scan module. Even if the module is disabled is a good idea to fill some information, because other modules can use it (like the VerificationIntervals for the notification module).
"time": "05:00:00 -0300",
Time of the day that you want that the scan to run (e.g. 05:00:00 BRT or 08:00:00 UTC). The scan will not occur exactly in the given time because of the scheduler architecture, it will probably have a delay of some minutes.
"intervalHours": 24,
Number of hours between each scan.
"numberOfQueriers": 400,
Number of parallel workers that will be sending queries to the registered nameservers. Remember that ideal number of queriers is defined by the hardware that you have.
"domainsBufferSize": 100,
Size of the buffer that process the domains, retrieving from database, sending requests and saving into database. This should be defined thinking on the number of queriers, because if there're many queries they will empty the buffer faster.
"errorsBufferSize": 100,
Size of the buffer that store errors of the scan.
"udpMaxSize": 4096,
The maximum size of a UDP package that your network can receive without being droppped by a firewall. Please, check EDNS0 for more information.
"saveAtOnce": 100,
Number of domains to accumulate before saving into database, this save us IO time and should be defined according to the number of queriers.
"connectionRetries": 3,
Number of times that a querier will retry to send the DNS request to the host. After that will consider a timeout problem.
Information about the recursive DNS server for specific services of the scan. Like QueryDomain, that retrieves the nameservers and DS records from a domain name.
"address": "8.8.8.8",
IP address from the resolver.
"port": 53
Port from the resolver.
Timeouts define the number of seconds that the system will wait for network operations.
"dialSeconds": 1,
Number of seconds that the system will wait while trying to connect to a remote host, for example, in a DNS request via TCP.
"readSeconds": 1,
Number of seconds that the system will wait for a response from the remote host.
"writeSeconds": 1
Number of seconds that the system will wait to receive an ack for the message written to a remote host via TCP.
Intervals days used for selecting registered domains to be scanned depending on the current domain state.
"maxOKDays": 7,
Maximum number of days that a well configured domain will wait until it is scanned again.
"maxErrorDays": 3,
Maximum number of days that a domain with DNS or DNSSEC configuration problems will wait until it is scanned again.
"maxExpirationAlertDays": 10
Maximum number of days before the DNSSEC expiration date that a domain will be verified for DNS or DNSSEC problems, and mainly to check if it was already resigned.
Store all variables related to the REST server.
"enabled": true,
Flag to enable or disable the REST server module. Even if the module is disabled is a good idea to fill the ACL and Secrets (for the WebClient module).
"languageConfigPath": "etc/messages.conf",
Path and filename of the REST messages file (messages.conf) that store all the messages that the REST server can return to a client on the desired language. The format of this file must follow JSON syntax and the following structure:
{
"default": "en-us",
"packs": [
{
"GenericName": "en",
"SpecificName": "en-us",
"Messages": {
"label1": "message1",
"label2": "message2",
...
"labelN": "messageN"
}
}TLS store the necessary data to allow an encrypted connection.
"certificatePath": "etc/keys/cert.pem",
X509 certificate (.pem) file.
"privateKeyPath": "etc/keys/key.pem"
X509 private key (.pem) file.
Addresses that the REST server will listen to.
"ip": "0.0.0.0",
IP address that can be IPv4 or IPv6.
"port": 4443,
Port number that will be used.
"tls": true
Flag that indicates if it will use HTTPS or not. All interfaces will use the same TLS certificates.
Number of seconds that the REST server will wait for network operations.
"readSeconds": 5,
Number of seconds that the system will wait for a response from the remote host.
"writeSeconds": 5
Number of seconds that the system will wait to receive an ack for the message written to a remote host.
List of IP ranges that are allowed to connect to the REST server, all other will receive a FORBIDDEN HTTP status code.
Store the shared secret keys used by the clients to sign the requests. The secrets are encrypted using the password command line tool distributed with this project.
Store all necessary information for the web client.
"enabled": true,
Flag to enable or disable the web client module.
"staticPath": "templates/client",
Base path where all html static content is found, like index.html, CSS and javascripts.
TLS store the necessary data to allow an encrypted connection.
"certificatePath": "etc/keys/cert.pem",
X509 certificate (.pem) file.
"privateKeyPath": "etc/keys/key.pem"
X509 private key (.pem) file.
Addresses that the web client will listen to.
"ip": "0.0.0.0",
IP address that can be IPv4 or IPv6.
"port": 4444,
Port number that will be used.
"tls": true
Flag that indicates if it will use HTTPS or not. All interfaces will use the same TLS certificates.
Store all notification related variables.
"enabled": true,
Flag to enable or disable the notification module.
"time": "07:00:00 -0300",
Time of the day that you want that the notification to run (e.g. 07:00:00 BRT or 10:00:00 UTC). The notification will not occur exactly in the given time because of the scheduler architecture, it will probably have a delay of some minutes. It is recommended to run the notification after the scan.
"intervalHours": 24,
Number of hours between each notification.
"nameserverErrorAlertDays": 7,
How many days we will wait with a DNS misconfigured nameserver until we notify the domain's owners.
"nameserverTimeoutAlertDays": 30,
How many days we will wait with a unresponsive nameserver until we notify the domain's owners.
"dsErrorAlertDays": 1,
How many days we will wait with a DNSSEC misconfigured nameserver until we notify the domain's owners.
"dsTimeoutAlertDays": 7,
How many days we will wait with a unresponsive nameserver for DNSSEC queries until we notify the domain's owners.
"from": "[email protected].",
All notification e-mails are sent with this From.
"templatesPath": "templates/notification",
Define the path that has the template files. Each template file must have the filename related to the language that it uses in lowercase (e.g. en-us.tmpl, pt-br.tmpl). The basic structure of each template should be as described bellow. The mail header and the parameters beteween "{{" and "}}" must not be removed, because they are used to build the basic structure of the notification.
{{$domain := .}}
From: {{.From}}
To: {{.To}}
Subject: Title
Some introduction message.
{{range $nameserver := $domain.Nameservers}}
{{if nsStatusEq $nameserver.LastStatus "TIMEOUT"}}
Error description.
{{else if nsStatusEq $nameserver.LastStatus "NOAA"}}
Error description.
{{else if nsStatusEq $nameserver.LastStatus "UDN"}}
Error description.
{{else if nsStatusEq $nameserver.LastStatus "UH"}}
Error description.
{{else if nsStatusEq $nameserver.LastStatus "SERVFAIL"}}
Error description.
{{else if nsStatusEq $nameserver.LastStatus "QREFUSED"}}
Error description.
{{else if nsStatusEq $nameserver.LastStatus "CREFUSED"}}
Error description.
{{else if nsStatusEq $nameserver.LastStatus "CNAME"}}
Error description.
{{else if nsStatusEq $nameserver.LastStatus "NOTSYNCH"}}
Error description.
{{else if nsStatusEq $nameserver.LastStatus "ERROR"}}
Error description.
{{end}}
{{end}}
{{range $ds := $domain.DSSet}}
{{if dsStatusEq $ds.LastStatus "TIMEOUT"}}
Error description.
{{else if dsStatusEq $ds.LastStatus "NOSIG"}}
Error description.
{{else if dsStatusEq $ds.LastStatus "EXPSIG"}}
Error description.
{{else if dsStatusEq $ds.LastStatus "NOKEY"}}
Error description.
{{else if dsStatusEq $ds.LastStatus "NOSEP"}}
Error description.
{{else if dsStatusEq $ds.LastStatus "SIGERR"}}
Error description.
{{else if dsStatusEq $ds.LastStatus "DNSERR"}}
Error description.
{{else if isNearExpiration $ds}}
Error description.
{{end}}
{{end}}
Goodbye message.
You can also use other variables in the template file, like {{$nameserver.Host}} or {{$ds.Keytag}} to create better user messages for the current scenario.
Store all necessary information to send notification e-mails using an SMTP server.
"server": "smtp.gmail.com",
Name or IP address of the SMTP server.
"port": 587,
Port of the SMTP server.
Authentication information of the SMTP server.
"type": "PLAIN",
Type of authentication, that can be empty, "PLAIN" or "CRAMMD5AUTH".
"username": "user",
Username used for authentication.
"password": "password"
Password used for authentication. The password is encrypted using the password command line tool distributed with this project.