Client resource
Configuration directives for the Client resource. Every directive is listed; value types and defaults are noted where the source provides them.
Address
Section titled “Address”Address = <address>
Where the <address> is a host name, a fully qualified domain name, or a network address in dotted quad notation for a NGBackup File server daemon. This directive is required.
AllowFDConnections
Section titled “AllowFDConnections”AllowFDConnections = <yes|no>
When AllowFDConnections is set to true, the Director will accept incoming connections from the Client and will keep the socket open for a future use. The Director will no longer use the Address to contact the File Daemon. This configuration is useful if the Director cannot contact the FileDaemon directly. See (here) for more information. The default value is no.
AutoPrune
Section titled “AutoPrune”AutoPrune = <yes|no>
If AutoPrune is set to yes (default), NGBackup (version 1.20 or greater) will automatically apply the File retention period and the Job retention period for the Client at the end of the Job. If you set AutoPrune = no, pruning will not be done, and your Catalog will grow in size each time you run a Job. Pruning affects only information in the catalog and not data stored in the backup archives (on Volumes).
Catalog
Section titled “Catalog”Catalog = <Catalog-resource-name>
This specifies the name of the catalog resource to be used for this Client. This directive is required.
Client (or FileDaemon)
Section titled “Client (or FileDaemon)”Start of the Client records. There must be one and only one Client resource in the configuration file, since it defines the properties of the current client program.
ClientRehydration
Section titled “ClientRehydration”ClientRehydration = <Directory>
This directive is optional and allows to try to do rehydration using existing local data on the Client at restore time. In some cases, the use of this directive permits to transfer less data over the network during a restore. The default value is no.
CommCompression
Section titled “CommCompression”CommCompression = <yes|no>
If the two NGBackup components (DIR, FD, SD, backup-console) have the comm line compression enabled, the line compression will be enabled. The default value is yes.
In many cases, the volume of data transmitted across the communications line can be reduced by a factor of three when this directive is enabled. In the case that the compression is not effective, NGBackup turns it off on a record by record basis.
If you are backing up data that is already compressed the comm line compression will not be effective, and you are likely to end up with an average compression ratio that is very small. In this case, NGBackup reports None in the Job report.
Dedup Index Directory
Section titled “Dedup Index Directory”Dedup Index Directory = <Directory>
This directive is deprecated and replaced by “Client Rehydration”.
This directive is optional and specifies a directory in which the File Daemon may put a index cache of all blocks read during a Backup job.
Standard shell expansion of the <Directory> is done when the configuration file is read so that values such as $HOME will be properly expanded.
DisableCommand
Section titled “DisableCommand”DisableCommand = <cmd>
The Disable Command adds security to your File daemon by disabling certain commands globally. The commands that can be disabled are:
`
backup cancel setdebug= setbandwidth= estimate fileset JobId= level = restore endrestore session status .status storage verify RunBeforeNow RunBeforeJob RunAfterJob Run accurate
`
One or more of these command keywords can be placed in quotes and separated by spaces on the Disable Command directive line. Note: the commands must be written exactly as they appear above.
Enabled
Section titled “Enabled”Enabled = <yes|no>
This directive allows you to enable or disable the Client resource. If the resource is disabled, the Client will not be used.
FD Port
Section titled “FD Port”FD Port = <port-number>
Where the <port-number> is a port number at which the NGBackup File server daemon can be contacted. The default is 9102.
FD Storage Address
Section titled “FD Storage Address”FD Storage Address = <address>
Where the <address> is a host name, a , or an IP address. The <address> specified here will be transmitted to the File daemon instead of the IP address that the Director uses to contact the Storage daemon. This FDStorageAddress will then be used by the File daemon to contact the Storage daemon. This directive particularly useful if the File daemon is in a different network domain than the Director or Storage daemon. It is also useful in NAT or firewal environments.
FDAddress
Section titled “FDAddress”FDAddress = <IP-Address>
This record is optional, and if it is specified, it will cause the File daemon server (for Director connections) to bind to the specified IP-Address, which is either a domain name or an IP address specified as a dotted quadruple. If this record is not specified, the File daemon will bind to any available address (the default).
FDAddresses
Section titled “FDAddresses”FDAddresses = <IP-address-specification>
Specify the ports and addresses on which the File daemon listens for Director connections. Probably the simplest way to explain is to show an example:
`
FDAddresses = { ip = { addr = 1.2.3.4; port = 1205; } ipv4 = { addr = 1.2.3.4; port = http; } ipv6 = { addr = 1.2.3.4; port = 1205; } ip = { addr = 1.2.3.4 port = 1205 } ip = { addr = 1.2.3.4 } ip = { addr = 201:220:222::2 } ip = { addr = bluedot.thun.net } }
`
where ip, ip4, ip6, addr, and port are all keywords. Note, that the address can be specified as either a dotted quadruple, or IPv6 colon notation, or as a symbolic name (only in the ip specification). Also, port can be specified as a number or as the mnemonic value from the /etc/services file. If a port is not specified, the default will be used. If an ip section is specified, the resolution can be made either by IPv4 or IPv6. If ip4 is specified, then only IPv4 resolutions will be permitted, and likewise with ip6.
FDPort
Section titled “FDPort”FDPort = <port-number>
This specifies the port number on which the Client listens for Director connections. It must agree with the FDPort specified in the Client resource of the Director’s configuration file. The default is 9102.
FDSourceAddress
Section titled “FDSourceAddress”FDSourceAddress = <IP-Address>
This record is optional, and if it is specified, it will cause the File daemon server (for Storage connections) to bind to the specified IP-Address, which is either a domain name or an IP address specified as a dotted quadruple. If this record is not specified, the kernel will choose the best address according to the routing table (the default).
File Retention
Section titled “File Retention”File Retention = <time-period-specification>
The File Retention directive defines the length of time that NGBackup will keep File records in the Catalog database after the End time of the Job corresponding to the File records. When this time period expires, and if AutoPrune is set to yes NGBackup will prune (remove) File records that are older than the specified File Retention period. Note, this affects only records in the catalog database. It does not affect your archive backups. File records may actually be retained for a shorter period than you specify on this directive if you specify either a shorter Job Retention or a shorter Volume Retention period. The shortest retention period of the three takes precedence. The time may be expressed in seconds, minutes, hours, days, weeks, months, quarters, or years. See the Configuration chapter of this manual for additional details of time specification.
The default is 60 days.
Heartbeat Interval
Section titled “Heartbeat Interval”Heartbeat Interval = <time-interval>
This record defines an interval of time in seconds. For each heartbeat that the File daemon receives from the Storage daemon, it will forward it to the Director. In addition, if no heartbeat has been received from the Storage daemon and thus forwarded the File daemon will send a heartbeat signal to the Director and to the Storage daemon to keep the channels active. The default interval is 300s. This feature is particularly useful if you have a router such as 3Com that does not follow Internet standards and times out a valid connection after a short duration despite the fact that keepalive is set. This usually results in a broken pipe error message. If you continue getting broken pipe error messages despite using the Heartbeat Interval, and you are using Windows, you should consider upgrading your ethernet driver. This is a known problem with NVidia NForce 3 drivers (4.4.2 17/05/2004), or try the following workaround suggested by Thomas Simmons for Win32 machines:
Browse to: Start → Control Panel → Network Connections
Right click the connection for the nvidia adapter and select properties. Under the General tab, click “Configure…”. Under the Advanced tab set “Checksum Offload” to disabled and click OK to save the change.
Lack of communications, or communications that get interrupted can also be caused by Linux firewalls where you have a rule that throttles connections or traffic.
Job Retention
Section titled “Job Retention”Job Retention = <time-period-specification>
The Job Retention directive defines the length of time that NGBackup will keep Job records in the Catalog database after the Job End time. When this time period expires, and if AutoPrune is set to yes NGBackup will prune (remove) Job records that are older than the specified File Retention period. As with the other retention periods, this affects only records in the catalog and not data in your archive backup. If a Job record is selected for pruning, all associated File and JobMedia records will also be pruned regardless of the File Retention period set. As a consequence, you normally will set the File retention period to be less than the Job retention period. The Job retention period can actually be less than the value you specify here if you set the Volume Retention directive in the Pool resource to a smaller duration. This is because the Job retention period and the Volume retention period are independently applied, so the smaller of the two takes precedence.
The Job retention period is specified as seconds, minutes, hours, days, weeks, months, quarters, or years. See the Configuration chapter of this manual for additional details of time specification.
The default is 180 days.
Maximum Bandwidth Per Job
Section titled “Maximum Bandwidth Per Job”Maximum Bandwidth Per Job = <speed>
The speed parameter specifies the maximum allowed bandwidth in bytes that a job may use when started for this Client. You may specify the following speed parameter modifiers: kb/s (1,000 bytes per second), k/s (1,024 bytes per second), mb/s (1,000,000 bytes per second), or m/s (1,048,576 bytes per second).
The use of TLS, TLS PSK, CommLine compression and Deduplication can interfer with the value set with the Directive.
Maximum Concurrent Jobs
Section titled “Maximum Concurrent Jobs”Maximum Concurrent Jobs = <number>
where <number> is the maximum number of Jobs with the current Client that can run concurrently. Note, this directive limits only Jobs for Clients with the same name as the resource in which it appears. Any other restrictions on the maximum concurrent jobs such as in the Director, Job, or Storage resources will also apply in addition to any limit specified here. The default is set to 1, but you may set it to a larger number. If set to a large value, please be careful to not have this value higher than the Maximum Concurrent Jobs configured in the Client resource in the Client/File daemon configuration file. Otherwise, backup jobs can fail due to the Director connection to FD be refused because Maximum Concurrent Jobs was exceeded on FD side.
Maximum Job Error Count
Section titled “Maximum Job Error Count”Maximum Job Error Count = <number>
where <number> is the error threshold for the Job, after reaching it Job will be failed. The default value is 1000. If this value is set to 0, job will continue to run no matter how many errors it encounters.
Maximum Network Buffer Size
Section titled “Maximum Network Buffer Size”Maximum Network Buffer Size = <bytes>
where <bytes> specifies the initial network buffer size to use with the File daemon. This size will be adjusted down if it is too large until it is accepted by the OS. Please use care in setting this value since if it is too large, it will be trimmed by 512 bytes until the OS is happy, which may require a large number of system calls. The default value is 65,536 bytes. The maximum value is 1,000,000 bytes. Note, on certain Windows machines, there are reports that the transfer rates are very slow and this seems to be related to the default 65,536 size. On systems where the transfer rates seem abnormally slow compared to other systems, you might try setting the Maximum Network Buffer Size to 32,768 in both the File daemon and in the Storage daemon.
Name = <name>
The client name that must be used by the Director when connecting. Generally, it is a good idea to use a name related to the machine so that error messages can be easily identified if you have multiple Clients. This directive is required.
Password
Section titled “Password”Password = <password>
This is the password to be used when establishing a connection with the File services, so the Client configuration file on the machine to be backed up must have the same password defined for this Director. This directive is required. If you have either /dev/random or bc on your machine, NGBackup will generate a random password during the configuration process, otherwise it will be left blank. The password is plain text. It is not generated through any special process, but it is preferable for security reasons to make the text random.
Pid Directory
Section titled “Pid Directory”Pid Directory = <Directory>
This directive is mandatory and specifies a directory in which the File daemon may put its process Id file files. The process Id file is used to shutdown NGBackup and to prevent multiple copies of NGBackup from running simultaneously. This record is required. Standard shell expansion of the <Directory> is done when the configuration file is read so that values such as $HOME will be properly expanded. Typically on Linux systems, you will set this to: /var/run. If you are not installing NGBackup in the system directories, you can use the Working Directory as defined above.
PKI Cipher
Section titled “PKI Cipher”This directive is optional and if specified will configure the data encryption to use a specific cipher. The default cipher is AES 128 CBC.
The following ciphers are available: aes128, aes192, aes256 and blowfish
PKI Digest
Section titled “PKI Digest”This directive is optional and if specified will configure the data encryption to use a specific digest algorithm. The default cipher is SHA1 or SHA256 depending on the version of OpenSSL.
The following digest are available: md5, sha1, sha256.
PKI Encryption
Section titled “PKI Encryption”See the Data Encryption chapter of this manual.
PKI Keypair
Section titled “PKI Keypair”See the Data Encryption chapter of this manual.
PKI Master Key
Section titled “PKI Master Key”See the Data Encryption chapter of this manual.
PKI Signatures
Section titled “PKI Signatures”See the Data Encryption chapter of this manual.
Port = <port-number>
Where the port is a port number at which the NGBackup File daemon can be contacted. The default is 9102.
Priority
Section titled “Priority”Priority = <number>
The number specifies the priority of this client relative to other clients that the Director is processing simultaneously. The priority can range from 1 to 1000. The clients are ordered such that the smaller number priorities are performed first (not currently implemented).
SD Calls Client
Section titled “SD Calls Client”SD Calls Client = <yes|no>
If the SD Calls Client directive is set to true in a Client resource any Backup, Restore, Verify Job where the client is involved, the client will wait for the Storage daemon to contact it. By default this directive is set to false, and the Client will call the Storage daemon as it always has. This directive can be useful if your Storage daemon is behind a firewall that permits outgoing connections but not incoming connections.
SD Packet Check
Section titled “SD Packet Check”SD Packet Check = <num-packets>
The SDPacketCheck takes a positive integer. The integer if zero turns off the feature. If the integer is greater than zero, it is the number of packets that the FileDaemon will send to the Storage Daemon before to send a POLL request and wait for the Storage Daemon answer. The default value is 0. If the time between two POLL requests is too short (less than few seconds) and the number of bytes transfered is less than few hundred of MB, the value of the SDPacketCheck is increased dynamically.
SDConnectTimeout
Section titled “SDConnectTimeout”SDConnectTimeout = <time-interval>
This record defines an interval of time that the File daemon will try to connect to the Storage daemon. The default is 30 minutes. If no connection is made in the specified time interval, the File daemon cancels the Job.
Snapshot Retention
Section titled “Snapshot Retention”Snapshot Retention = <time-period-specification>
The Snapshot Retention directive defines the length of time that NGBackup will keep Snapshots in the Catalog database and on the Client after the Snapshot creation. When this time period expires, and if using the snapshot prune command, NGBackup will prune (remove) Snapshot records that are older than the specified Snapshot Retention period and will contact the FileDaemon to delete Snapshots from the system.
The Snapshot retention period is specified as seconds, minutes, hours, days, weeks, months, quarters, or years. See the Configuration chapter of this manual for additional details of time specification.
The default is 0 seconds, Snapshots are deleted at the end of the backup. The Job SnapshotRetention directive overwrites the Client SnapshotRetention directive.
TLS Allowed CN
Section titled “TLS Allowed CN”TLS Allowed CN = <string list>
Common name attribute of allowed peer certificates. This directive is valid for a server and in a client context. If this directive is specified, the peer certificate will be verified against this list. In the case this directive is configured on a server side, the allowed CN list will not be checked if TLS Verify Peer is set to no (TLS Verify Peer is yes by default). This can be used to ensure that only the CN-approved component may connect. This directive may be specified more than once. In the case this directive is configured in a server side, the allowed CN list will only be checked if TLS Verify Peer = yes (default). For example, in backup-fd.conf, Director resource definition:
`
Director { Name = backup-dir Password = “password” Address = director.example.com
TLS configuration directives
Section titled “TLS configuration directives”TLS Enable = yes TLS Require = yes
if TLS Verify Peer = no, then TLS Allowed CN will not be checked.
Section titled “if TLS Verify Peer = no, then TLS Allowed CN will not be checked.”TLS Verify Peer = yes TLS Allowed CN = director.example.com TLS CA Certificate File = /opt/backup/ssl/certs/root_cert.pem TLS Certificate = /opt/backup/ssl/certs/client1_cert.pem TLS Key = /opt/backup/ssl/keys/client1_key.pem }
`
In the case this directive is configured in a client side, the allowed CN list will always be checked.
`
Client { Name = client1-fd Address = client1.example.com FDPort = 9102 Catalog = MyCatalog Password = “password” …
TLS configuration directives
Section titled “TLS configuration directives”TLS Enable = yes TLS Require = yes
the Allowed CN will be checked for this client by director
Section titled “the Allowed CN will be checked for this client by director”the client’s certificate Common Name must match any of
Section titled “the client’s certificate Common Name must match any of”the values of the Allowed CN list
Section titled “the values of the Allowed CN list”TLS Allowed CN = client1.example.com TLS CA Certificate File = /opt/backup/ssl/certs/ca_client1_cert.pem TLS Certificate = /opt/backup/ssl/certs/director_cert.pem TLS Key = /opt/backup/ssl/keys/director_key.pem }
`
If the client doesnât provide a certificate with a Common Name that meets any value in the TLS Allowed CN list, an error message will be issued:
`
16-Nov 17:30 backup-dir JobId 0: Fatal error: bnet.c:273 TLS certificate verification failed. Peer certificate did not match a required commonName 16-Nov 17:30 backup-dir JobId 0: Fatal error: TLS negotiation failed with FD at “192.168.100.2:9102”.
`
TLS Authenticate
Section titled “TLS Authenticate”TLS Authenticate = <yes|no>
When TLS Authenticate is enabled, after doing the CRAM-MD5 authentication, NGBackup will also do TLS authentication, then TLS encryption will be turned off, and the rest of the communication between the two NGBackup components will be done without encryption. If TLS-PSK is used instead of the regular TLS, the encryption is turned off after the TLS-PSK authentication step. If you want to encrypt communications data, use the normal TLS directives but do not turn on TLS Authenticate.
TLS CA Certificate Dir
Section titled “TLS CA Certificate Dir”TLS CA Certificate Dir = <Directory>
Full path to TLS CA certificate directory. In the current implementation, certificates must be stored PEM encoded with OpenSSL-compatible hashes, which is the subject name’s hash and an extension of .0. One of TLS CA Certificate File or TLS CA Certificate Dir are required in a server context, unless TLS Verify Peer is set to no, and are always required in a client context.
TLS CA Certificate File
Section titled “TLS CA Certificate File”TLS CA Certificate File = <Filename>
The full path and filename specifying a PEM encoded TLS CA certificate(s). Multiple certificates are permitted in the file. One of TLS CA Certificate File or TLS CA Certificate Dir are required in a server context, unless TLS Verify Peer (see above) is set to no, and are always required in a client context.
TLS Certificate
Section titled “TLS Certificate”TLS Certificate = <Filename>
The full path and filename of a PEM encoded TLS certificate. It will be used as either a client or server certificate, depending on the connection direction. PEM stands for Privacy Enhanced Mail, but in this context refers to how the certificates are encoded. This format is used because PEM files are base64 encoded and hence ASCII text based rather than binary. They may also contain encrypted information. This directive is required in a server context, but it may not be specified in a client context if TLS Verify Peer is set to no in the corresponding server context.
Example:
File Daemon configuration file (backup-fd.conf), Director resource configuration has TLS Verify Peer = no:
`
Director { Name = backup-dir Password = “password” Address = director.example.com
TLS configuration directives
Section titled “TLS configuration directives”TLS Enable = yes TLS Require = yes TLS Verify Peer = no TLS CA Certificate File = /opt/backup/ssl/certs/root_cert.pem TLS Certificate = /opt/backup/ssl/certs/client1_cert.pem TLS Key = /opt/backup/ssl/keys/client1_key.pem }
`
Having TLS Verify Peer = no, means the File Daemon, server context, will not check Directorâs public certificate, client context. There is no need to specify TLS Certificate File neither TLS Key directives in the Client resource, director configuration file. We can have the below client configuration in backup-dir.conf:
`
Client { Name = client1-fd Address = client1.example.com FDPort = 9102 Catalog = MyCatalog Password = “password” …
TLS configuration directives
Section titled “TLS configuration directives”TLS Enable = yes TLS Require = yes TLS CA Certificate File = /opt/backup/ssl/certs/ca_client1_cert.pem }
`
TLS DH File
Section titled “TLS DH File”TLS DH File = <Directory>
Path to PEM encoded Diffie-Hellman parameter file. If this directive is specified, DH key exchange will be used for the ephemeral keying, allowing for forward secrecy of communications. DH key exchange adds an additional level of security because the key used for encryption/decryption by the server and the client is computed on each end and thus is never passed over the network if Diffie-Hellman key exchange is used. Even if DH key exchange is not used, the encryption/decryption key is always passed encrypted. This directive is only valid within a server context. To generate the parameter file, you may use openssl:
`
openssl dhparam -out dh4096.pem -5 4096
`
TLS Enable
Section titled “TLS Enable”TLS Enable = <yes|no>
Enable TLS support. If TLS is not enabled, none of the other TLS directives have any effect. In other words, even if you set TLS Require = yes you need to have TLS enabled or TLS will not be used.
TLS Key
Section titled “TLS Key”TLS Key = <Filename>
The full path and filename of a PEM encoded TLS private key. It must correspond to the TLS certificate.
TLS PSK Enable
Section titled “TLS PSK Enable”TLS PSK Enable = <yes|no>
Enable or Disable automatic TLS PSK support. TLS PSK is enabled by default between all NGBackup components. The Pre-Shared Key used between the programs is the NGBackup password. If both TLS Enable and TLS PSK Enable are enabled, the system will use TLS certificates.
TLS Require
Section titled “TLS Require”TLS Require = <yes|no>
Require TLS or TLS-PSK encryption. This directive is ignored unless one of TLS Enable or TLS PSK Enable is set to yes. If TLS is not required while TLS or TLS-PSK are enabled, then the NGBackup component will connect with other components either with or without TLS or TLS-PSK
If TLS or TLS-PSK is enabled and TLS is required, then the NGBackup component will refuse any connection request that does not use TLS.
TLS Verify Peer
Section titled “TLS Verify Peer”TLS Verify Peer = <yes|no>
Verify peer certificate. Instructs server to request and verify the client’s X.509 certificate. Any client certificate signed by a known-CA will be accepted. Additionally, the client’s X509 certificate Common Name must meet the value of the Address directive. If the TLSAllowed CN onfiguration directive is used, the client’s x509 certificate Common Name must also correspond to one of the CN specified in the TLS Allowed CN directive. This directive is valid only for a server and not in client context. The default is yes.
Working Directory
Section titled “Working Directory”Working Directory = <Directory>
This directive is mandatory and specifies a directory in which the File daemon may put its status files. This directory should be used only by NGBackup, but may be shared by other NGBackup daemons provided the daemon names on the Name definition are unique for each daemon. This directive is required. On Win32 systems, in some circumstances you may need to specify a drive letter in the specified working directory path. Also, please be sure that this directory is writable by the SYSTEM user otherwise restores may fail (the bootstrap file that is transferred to the File daemon from the Director is temporarily put in this directory before being passed to the Storage daemon).