Refactorings + updated documentation 0.0.3-2

Author: jantytgat

README.md

@@ -1,93 +1,137 @@
 # CoreLayer.Citrix.Adc.NodeBackup
 
 
-## Introduction
+## 1. Introduction
 
 This project allows you to automatically backup your Citrix ADC (formerly known as NetScaler) configuration to a filepath available to the client.
 Developed in .NetCore using C#, we provide a fully running application in several flavors:
 - Single-file executables for Linux, MacOS and Windows
 - Dotnet-dependent DLL
 - Linux container (https://hub.docker.com/r/corelayer/corelayer-citrix-adc-nodebackupservice)
 
-## Prerequisites
-### Citrix ADC Configuration
+---
+## 2. Configuration
+### 2.1. Prerequisites
+#### 2.1.1. Citrix ADC
 
 For optimal security, create a separate user on Citrix ADC for backup purposes.
-The command policy below limits the allowed commands to the absolute minimum:
+The command policy below limits the allowed commands to the absolute minimum.
 
-```
+*Replace <username> and <password> with values of your own choosing.*
+
+```text
 add system cmdPolicy corelayer_backup ALLOW "(^(show\\s+system\\s+backup)|(create|rm)\\s+system\\s+backup\\s+.*)|(^show\\ssystem\\sfile\\s[\\w\\.-]+\\s-fileLocation\\s\"/var/ns_sys_backup\")"
 
 
 add system user <username> <password> -externalAuth DISABLED -timeout 900 -allowedManagementInterface API
 bind system user backup corelayer_backup 0
 ```
 
-## Running the application
-### Docker-compose
-#### Template configuration
-```
+### 2.2. NodeBackup
+NodeBackup can be configured using the following options.
+
+Depending on your enviroment, you may choose to provide values for these parameters in one of the following ways:
+
+|Provider|Target|
+|---|---|
+|Configuration file|appsettings.json|
+|Environment variables|Environment variable per option|
+|Command-line parameters|Parameter per option|
+
+#### 2.2.1. Node Configuration:
+
+|Parameter|Value|Default|Description|
+|---|---|---|---|
+|Organization|CoreLayer|N/A|Organization Name|
+|Environment|Production|N/A|ADC Environment Name|
+|NodeName|nsprod|N/A|ADC Node Name|
+|NodeAddress|https://nsprod.prd.corelayer.local|N/A|ADC NSIP or URL|
+|Username|backup|N/A|Username|
+|Password|backup|N/A|Password|
+|CertificateValidation|Disabled|Enabled|Validate ADC SSL certificate (Disable for self-signed certificates|
+
+#### 2.2.2. Backup Configuration:
+
+|Parameter|Value|Default|Description|
+|---|---|---|---|
+|Start|00:00|N/A|Start time for backups (HH:MM)|
+|Interval|3600|3600|Interval in seconds, must be factor of 300 (5minutes)|
+|BasePath|/var/corelayer/adc/nodebackup|N/A|Base path to store backups|
+|CreateSubdirectoryForNode|true|true|Create a subdirectory for the node|
+
+#### 2.2.3. Prometheus Configuration:
+
+|Parameter|Value|Default|Description|
+|---|---|---|---|
+|Enable Metrics Server|true|true|Enable the Prometheus Metrics Endpoint|
+|Metrics Server Port|5000|5000|TCP Endpoint for the Metrics server|
+|Metrics Server Use https|false|true|Run the TCP Endpoint with https|
+|Metrics Name Prefix|corelayer|corelayer|Prefix for the metric names|
+
+## 3. Platforms
+### 3.1. Docker
+#### 3.1.1. Docker-compose
+##### 3.1.1.1. Template configuration
+
+- *Replace __nodename__ with the actual node name.*
+- *Replace the __hostport__ with the desired external port number.*
+
+```yaml
 version: '3'
 services:
-  nsprod-nodebackup-service:
+  nodename-nodebackup-service:
     image: corelayer/corelayer-citrix-adc-nodebackupservice:dev-latest
-    container_name: nsprod-nodebackupservice
+    container_name: nodename-nodebackupservice
     environment:
       - Logging__LogLevel__Default=Information
-      - NodeBackupConfiguration__Node__OwnerName=Organization
-      - NodeBackupConfiguration__Node__EnvironmentName=Environment
-      - NodeBackupConfiguration__Node__NodeName=NodeName
-      - NodeBackupConfiguration__Node__NodeAddress=(http|https)://(IP|URL)
-      - NodeBackupConfiguration__Node__Username=Username
-      - NodeBackupConfiguration__Node__Password=Password
-      - NodeBackupConfiguration__Node__CertificateValidation=(Enabled|Disabled)
-      - NodeBackupConfiguration__Backup__Start=(HH:mm)
-      - NodeBackupConfiguration__Backup__Interval=1800
-      - NodeBackupConfiguration__Backup__BasePath=/var/corelayer/adc/nodebackup/
-      - NodeBackupConfiguration__Backup__CreateSubdirectoryForNode=(true | false)
-      - NodeBackupConfiguration__Prometheus__EnableMetricsServer=(true | false)
-      - NodeBackupConfiguration__Prometheus__NamePrefix=corelayer
+      - NodeBackupConfiguration__Node__OwnerName=
+      - NodeBackupConfiguration__Node__EnvironmentName=
+      - NodeBackupConfiguration__Node__NodeName=
+      - NodeBackupConfiguration__Node__NodeAddress=
+      - NodeBackupConfiguration__Node__Username=
+      - NodeBackupConfiguration__Node__Password=
+      - NodeBackupConfiguration__Node__CertificateValidation=
+      - NodeBackupConfiguration__Backup__Start=
+      - NodeBackupConfiguration__Backup__Interval=
+      - NodeBackupConfiguration__Backup__BasePath=
+      - NodeBackupConfiguration__Backup__CreateSubdirectoryForNode=
+      - NodeBackupConfiguration__Prometheus__MetricsServer__Enabled=
+      - NodeBackupConfiguration__Prometheus__MetricsServer__Port=5000
+      - NodeBackupConfiguration__Prometheus__MetricsServer__UseHttps=
+      - NodeBackupConfiguration__Prometheus__NamePrefix=
     volumes:
        - $PWD:/var/corelayer/adc/nodebackup
+    ports:
+       - "hostport:5000/tcp"
 ```
 
-#### Example
-Example values for the configuration
-- Organization: CoreLayer
-- Environment: Production
-- NodeName: nsprod
-- NodeAddress: https://nsprod.prd.corelayer.local
-- Username: backup
-- Password: backup
-- CertificateValidation: false
-- Start: 00:00 (Hours:Minutes)
-- Interval: 1800 (in seconds, must be factor of 300)
-- BasePath: /var/corelayer/adc/nodebackup
-- CreateSubdirectoryForNode: Enabled
-- EnableMetricsServer: true
-- NamePrefix: corelayer (metric names prefix)
+#### 2.3.2 Example
 
-```
+```yaml
 version: '3'
 services:
-  nsprod-nodebackup-service:
+  <nodename>-nodebackup-service:
     image: corelayer/corelayer-citrix-adc-nodebackupservice:dev-latest
-    container_name: nsprod-nodebackupservice
+    container_name: <nodename>-nodebackupservice
     environment:
       - Logging__LogLevel__Default=Information
       - NodeBackupConfiguration__Node__OwnerName=CoreLayer
       - NodeBackupConfiguration__Node__EnvironmentName=Production
-      - NodeBackupConfiguration__Node__NodeName=nsprod
-      - NodeBackupConfiguration__Node__NodeAddress=https://nsprod.prd.corelayer.local
+      - NodeBackupConfiguration__Node__NodeName=nsprod01
+      - NodeBackupConfiguration__Node__NodeAddress=https://nsprod01.corelayer.local
       - NodeBackupConfiguration__Node__Username=backup
       - NodeBackupConfiguration__Node__Password=backup
-      - NodeBackupConfiguration__Node__CertificateValidation=disabled
+      - NodeBackupConfiguration__Node__CertificateValidation=Enabled
       - NodeBackupConfiguration__Backup__Start=00:00
-      - NodeBackupConfiguration__Backup__Interval=1800
-      - NodeBackupConfiguration__Backup__BasePath=/var/corelayer/adc/nodebackup/
+      - NodeBackupConfiguration__Backup__Interval=3600
+      - NodeBackupConfiguration__Backup__BasePath=/var/corelayer/adc/nodebackup
       - NodeBackupConfiguration__Backup__CreateSubdirectoryForNode=true
-      - NodeBackupConfiguration__Prometheus__EnableMetricsServer=true
+      - NodeBackupConfiguration__Prometheus__MetricsServer__Enabled=true
+      - NodeBackupConfiguration__Prometheus__MetricsServer__Port=5000
+      - NodeBackupConfiguration__Prometheus__MetricsServer__UseHttps=false
       - NodeBackupConfiguration__Prometheus__NamePrefix=corelayer
     volumes:
        - $PWD:/var/corelayer/adc/nodebackup
+    ports:
+       - "5000:5000/tcp"
 ```

src/CoreLayer.Citrix.Adc.NodeBackup/CoreLayer.Citrix.Adc.NodeBackupWorker/Configuration/BackupConfiguration.cs

@@ -5,8 +5,8 @@ namespace CoreLayer.Citrix.Adc.NodeBackupWorker.Configuration
     public class BackupConfiguration
     {
         public DateTime Start { get; set; }
-        public int Interval { get; set; }
+        public int Interval { get; set; } = 3600;
         public string BasePath { get; set; }
-        public bool CreateSubdirectoryForNode { get; set; }
+        public bool CreateSubdirectoryForNode { get; set; } = true;
     }
 }

src/CoreLayer.Citrix.Adc.NodeBackup/CoreLayer.Citrix.Adc.NodeBackupWorker/Configuration/NodeConfiguration.cs

@@ -10,7 +10,9 @@ public class  NodeConfiguration
         public string NodeName { get; set; }
 
         public Uri NodeAddress { get; set; }
-        public NitroHttpClientCertificateValidation CertificateValidation { get; set; }
+
+        public NitroHttpClientCertificateValidation CertificateValidation { get; set; } =
+            NitroHttpClientCertificateValidation.Enabled;
 
         public string Username { get; set; }
         public string Password { get; set; }

src/CoreLayer.Citrix.Adc.NodeBackup/CoreLayer.Citrix.Adc.NodeBackupWorker/Configuration/PrometheusConfiguration.cs

@@ -2,7 +2,7 @@ namespace CoreLayer.Citrix.Adc.NodeBackupWorker.Configuration
 {
     public class PrometheusConfiguration
     {
-        public bool EnableMetricsServer { get; set; } = false;
+        public PrometheusMetricsServerConfiguration MetricsServer { get; set; }
         public string NamePrefix { get; set; } = "corelayer";
     }
 }

src/CoreLayer.Citrix.Adc.NodeBackup/CoreLayer.Citrix.Adc.NodeBackupWorker/Configuration/PrometheusMetricsServerConfiguration.cs

@@ -0,0 +1,9 @@
+namespace CoreLayer.Citrix.Adc.NodeBackupWorker.Configuration
+{
+    public class PrometheusMetricsServerConfiguration
+    {
+        public bool Enabled { get; set; }
+        public int Port { get; set; } = 5000;
+        public bool UseHttps { get; set; } = false;
+    }
+}

src/CoreLayer.Citrix.Adc.NodeBackup/CoreLayer.Citrix.Adc.NodeBackupWorker/NodeBackupHostedService.cs

@@ -59,7 +59,7 @@ public NodeBackupHostedService(IHostApplicationLifetime hostApplicationLifetime,
             // Configure timer
             _logger.LogDebug("Configuring NodeBackup Timer");
             _timer = new System.Timers.Timer(_nodeBackupConfiguration.Backup.Interval * 1000);
-            _timer.Elapsed += TriggerNodeBackup;
+            _timer.Elapsed += OnBackupTimerElapsed;
 
             // Configure output
             _logger.LogDebug("Configuring Output path");
@@ -89,9 +89,12 @@ public NodeBackupHostedService(IHostApplicationLifetime hostApplicationLifetime,
                 hostApplicationLifetime.StopApplication();
 
             // Start embedded Prometheus MetricsServer
-            if (!_nodeBackupConfiguration.Prometheus.EnableMetricsServer) return;
+            if (!_nodeBackupConfiguration.Prometheus.MetricsServer.Enabled) return;
             _logger.LogInformation("Starting metrics server");
-            _metricServer = new MetricServer(hostname: "localhost", port: 5001, useHttps: false);
+            _metricServer = new MetricServer(
+                hostname: "localhost", 
+                port: _nodeBackupConfiguration.Prometheus.MetricsServer.Port, 
+                useHttps: _nodeBackupConfiguration.Prometheus.MetricsServer.UseHttps);
             _metricServer.Start();
         }
 
@@ -222,82 +225,95 @@ protected override async Task ExecuteAsync(CancellationToken cancellationToken)
             _logger.LogDebug("Waiting 5 seconds before starting countdown");
             await Task.Delay(5000, cancellationToken);
 
-            await TriggerExecutionTimer(cancellationToken);
+            await ExecutionLoopAsync(cancellationToken);
 
             _logger.LogInformation("Stopping backup timer");
             _timer.Stop();
         }
 
-        private async Task TriggerExecutionTimer(CancellationToken cancellationToken)
+        private async Task ExecutionLoopAsync(CancellationToken cancellationToken)
         {
             while (!cancellationToken.IsCancellationRequested)
             {
-                var nextIntervalCountdown = CalculateNextTargetSeconds();
+                var nextIntervalSeconds = CalculateNextIntervalSeconds();
 
                 if (!_timer.Enabled)
                 {
-                    if (nextIntervalCountdown == 300)
+                    if (nextIntervalSeconds == _nodeBackupConfiguration.Backup.Interval)
                     {
                         _logger.LogInformation("Starting backup timer");
                         _timer.Enabled = true;
                         await ExecuteBackupProcedure(DateTime.Now);
                     }
                     else
                     {
-                        _logger.LogInformation("Counting down to backup timer start: {0}",
-                            nextIntervalCountdown.ToString());
+                        _logger.LogInformation("Counting down to backup timer start: {0} at {1} - {2} seconds",
+                            TimeSpan.FromSeconds(nextIntervalSeconds).ToString(@"hh\:mm\:ss"),
+                            TimeSpan.FromSeconds(DateTime.Now.Ticks / TimeSpan.TicksPerSecond + nextIntervalSeconds).ToString(@"hh\:mm\:ss"),
+                            nextIntervalSeconds.ToString());
                     }
                 }
                 else
                 {
-                    _logger.LogDebug("Counting down to next backup: {0}", nextIntervalCountdown.ToString());
+                    _logger.LogInformation("Counting down to next backup: {0} at {1} - {2} seconds",
+                        TimeSpan.FromSeconds(nextIntervalSeconds).ToString(@"hh\:mm\:ss"),
+                        TimeSpan.FromSeconds(DateTime.Now.Ticks / TimeSpan.TicksPerSecond + nextIntervalSeconds).ToString(@"hh\:mm\:ss"),
+                        nextIntervalSeconds.ToString());
                 }
+                
                 await Task.Delay(1000, cancellationToken);
             }
         }
 
-        private long CalculateNextTargetSeconds()
+        private long CalculateNextIntervalSeconds()
         {
-            long nextTargetSeconds;
-            
-            if (DateTime.Now.Ticks / TimeSpan.TicksPerSecond < _nodeBackupConfiguration.Backup.Start.Ticks / TimeSpan.TicksPerSecond)
-            {
-                _logger.LogDebug("Current time is before target start time");
-                nextTargetSeconds = ((_nodeBackupConfiguration.Backup.Start.Ticks - DateTime.Now.Ticks) /
-                                     TimeSpan.TicksPerSecond);
-                
-                if (nextTargetSeconds > _nodeBackupConfiguration.Backup.Interval)
-                {
-                    nextTargetSeconds -= _nodeBackupConfiguration.Backup.Interval;
+            return
+                DateTime.Now.Ticks / TimeSpan.TicksPerSecond < _nodeBackupConfiguration.Backup.Start.Ticks / TimeSpan.TicksPerSecond 
+                    ? CalculateIntervalSecondsFromNowToBackupStart() : CalculateIntervalSecondsFromBackupStartToNow();
+        }
 
-                    _logger.LogDebug(
-                        "Seconds to next interval : {0}",
-                        nextTargetSeconds.ToString());
-                }
+        private long CalculateIntervalSecondsFromBackupStartToNow()
+        {
+            _logger.LogDebug("Current time is later than target start time");
+            var nextTargetSeconds = ((DateTime.Now.Ticks - _nodeBackupConfiguration.Backup.Start.Ticks) /
+                                     TimeSpan.TicksPerSecond);
 
-                nextTargetSeconds++;
-            }
+            if (nextTargetSeconds < 0)
+                nextTargetSeconds = _nodeBackupConfiguration.Backup.Interval - nextTargetSeconds;
             else
             {
-                _logger.LogDebug("Current time is later than target start time");
-                nextTargetSeconds = ((DateTime.Now.Ticks - _nodeBackupConfiguration.Backup.Start.Ticks) /
-                                     TimeSpan.TicksPerSecond);
+                nextTargetSeconds = _nodeBackupConfiguration.Backup.Interval -
+                                    nextTargetSeconds % _nodeBackupConfiguration.Backup.Interval;
+            }
+
+            _logger.LogDebug(
+                "Seconds to next interval : {0}",
+                nextTargetSeconds.ToString());
+
+            return nextTargetSeconds;
+        }
+
+        private long CalculateIntervalSecondsFromNowToBackupStart()
+        {
+            _logger.LogDebug("Current time is before target start time");
+            var nextTargetSeconds = (_nodeBackupConfiguration.Backup.Start.Ticks - DateTime.Now.Ticks) /
+                                     TimeSpan.TicksPerSecond;
+
+            if (nextTargetSeconds > _nodeBackupConfiguration.Backup.Interval)
+            {
+                nextTargetSeconds -= _nodeBackupConfiguration.Backup.Interval;
 
-                if (nextTargetSeconds < 0)
-                    nextTargetSeconds = 300 - nextTargetSeconds;
-                else
-                {
-                    nextTargetSeconds = _nodeBackupConfiguration.Backup.Interval - nextTargetSeconds % _nodeBackupConfiguration.Backup.Interval;
-                }
                 _logger.LogDebug(
                     "Seconds to next interval : {0}",
                     nextTargetSeconds.ToString());
             }
-            
+
+            nextTargetSeconds++;
+
             return nextTargetSeconds;
         }
 
-        private async void TriggerNodeBackup(Object source, ElapsedEventArgs e)
+        private async void OnBackupTimerElapsed(Object source, ElapsedEventArgs e)
         {
             _logger.LogInformation("Backup was triggered at {0:HH:mm:ss}",
                 e.SignalTime);