From 6f5b1a6d1b7f80f4ff2056fd3c166d09b679a5f9 Mon Sep 17 00:00:00 2001 From: Shain Singh Date: Tue, 28 May 2024 13:04:34 +1000 Subject: [PATCH] docs: update README, INSTALL and USAGE --- INSTALL.md | 70 ++++++++++++++++++++++++++++++++++++++++++++--------- README.md | 21 +++++++--------- SECURITY.md | 40 +++++++++++++++++++++++++++--- USAGE.md | 13 ++++++---- 4 files changed, 113 insertions(+), 31 deletions(-) diff --git a/INSTALL.md b/INSTALL.md index dc078db..180a833 100644 --- a/INSTALL.md +++ b/INSTALL.md @@ -1,3 +1,5 @@ +# Installation Instructions + ## Prerequisites Before you begin, ensure that you have: @@ -6,6 +8,8 @@ Before you begin, ensure that you have: - Administrative privileges on the system - Internet access to download necessary files +[Running the script via a service account](#creating-a-service-account) + ## Installation Steps > [!NOTE] @@ -39,26 +43,70 @@ Before you begin, ensure that you have: cd f5xc-backup-restore-utils ``` -5. **Install Required Python Modules** - The script requires certain Python modules to function. Install them using the `pip` command: - - ```bash - sudo python3 -m pip install -r requirements.txt - ``` - -6. **Set Execution Permissions** +5. **Set Execution Permissions** Make the script executable with the following command: ```bash chmod +x f5xc-backup-restore.py ``` -7. **Configure the Script** - Before running the script, you need to configure it with your F5XC Tenant URL and API Token. Open the script in a text editor and enter your details where required. +6. **Checking credentials** + Before running the script, you need to configure it with your F5XC Tenant URL and API Token. Refer to [the following to create a config.ini file with your credentials](./SECURITY.md#credentials) -8. **Run the Script** +7. **Run the Script** You can now run the backup or restore script using the following commands: ```bash ./f5xc-backup-restore.py ``` + +## Creating a Service Account + +1. **Create a New User** + Create a new user account on the Linux system with the following command: + + ```bash + sudo useradd -m f5xc-service-account + ``` + +2. **Set a Password** + Set a password for the new user account: + + ```bash + sudo passwd f5xc-service-account + ``` + +3. **Create a New Group** + Create a new group for the service account: + + ```bash + sudo groupadd f5xc-operations-group + ``` + +4. **Add the User to the Group** + Add the user to the group: + + ```bash + sudo usermod -a -G f5xc-operations-group f5xc-service-account + ``` + +5. **Installing script to an accessible location** + Copy the script to a location accessible by the service account: + + ```bash + sudo cp f5xc-backup-restore.py /usr/local/bin + ``` + +6. **Set Permissions** + Set the permissions on the script to allow execution from a service account and its group: + + ```bash + sudo chmod 750 /usr/local/bin/f5xc-backup-restore.py + ``` + +7. **Set Ownership** + Set the ownership of the script to the service account and group: + + ```bash + sudo chown f5xc-service-account:f5xc-operations-group /usr/local/bin/f5xc-backup-restore.py + ``` diff --git a/README.md b/README.md index 9043652..933d929 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -# F5 Distributed Cloud Backup/Restore Operations +# F5 Distributed Cloud Backup and Restore Operations [![Project Status: Active – The project has reached a stable, usable state and is being actively developed.](https://www.repostatus.org/badges/latest/active.svg)](https://www.repostatus.org/#active) [![GitHub branch checks state](https://img.shields.io/github/checks-status/f5devcentral/f5xc-backup-restore-utils/main?label=build%20checks)](https://github.com/f5devcentral/f5xc-backup-restore-utils/actions) @@ -18,7 +18,7 @@ This repository contains tools designed to help network operations staff save an [Example Output](#example-output) > [!IMPORTANT] -> The following configuration objects from F5 Distributed Cloud are supported for backup and restore functions only: +> The script in this repository will support the following configuration objects from F5 Distributed Cloud for backup and restore functions: > > - HTTP Load Balancer > - TCP Load Balancer @@ -44,9 +44,9 @@ This repository contains tools designed to help network operations staff save an Before using these tools, you need to have the following: - **Python 3.x**: This is the programming language in which the script is written. You need to have it installed on your system to run the script. -- **F5 Distributed Cloud Tenant URL**: This is the web address of your specific network management area. -- **F5 Distributed Cloud API Token**: This is a special code that allows the script to access and modify your network settings. You can obtain an API Token by following the instructions provided in the F5 documentation [here](https://docs.cloud.f5.com/docs/how-to/user-mgmt/credentials). -- **F5 Distributed Cloud Namespace**: Before running the restore function, make sure the namespace (a specific area within your tenant where settings are applied) exists. +- **F5 Distributed Cloud Tenant URL**: This is the web address of your specific F5 Distributed Cloud tenant. +- **F5 Distributed Cloud API Token**: This is a credential that allows the script to modify settings inside your F5 Distributed Cloud tenant. You can obtain an API Token by following the instructions provided in the F5 documentation [here](https://docs.cloud.f5.com/docs/how-to/user-mgmt/credentials). +- **F5 Distributed Cloud Namespace**: Before running any restore operations with the script, make sure the namespace (a specific area within your tenant where settings are applied) exists. ## Installation @@ -61,11 +61,10 @@ Refer to [USAGE.md](/USAGE.md) for usage instructions. The following is an example of output from a backup: ```bash - $ python3 f5xc-backup-restore.py -a backup -p /var/backup -n mcn-sample ====================================================================================================================== -[STARTED] Date: 2024-02-21 07:05:26 UTC Tenant: f5-xctestdrive TASK: BACKUP Namespace: mcn-sample +[STARTED] Date: 2024-02-21 07:05:26 UTC Tenant: f5xc-testdrive TASK: BACKUP Namespace: mcn-sample ====================================================================================================================== [mcn-sample] Backing up HTTP Loadbalancer object [mcn-sample-lb] ..... DONE [mcn-sample] Backing up Origin Pool object [mcn-sample-originpool] ..... DONE @@ -73,19 +72,17 @@ $ python3 f5xc-backup-restore.py -a backup -p /var/backup -n mcn-sample [mcn-sample] Backing up App Firewall object [mcn-sample-appfw] ..... DONE [mcn-sample] Backing up Malicious User Mitigation object [mcn-sample-maluser-policy] ..... DONE ================================================================================================================ -[COMPLETED] Date: 2024-02-21 07:05:58 UTC Tenant: f5-xctestdrive +[COMPLETED] Date: 2024-02-21 07:05:58 UTC Tenant: f5xc-testdrive ================================================================================================================ - ``` The following is an example of output from a restore: ```bash - $ python3 f5xc-backup-restore.py -a restore -p /var/backup/f5xc-backup-20240221_070526/ -n mcn-sample ================================================================================================================================== -[STARTED] Date: 2024-02-21 07:09:50 UTC Tenant: f5-xctestdrive TASK: RESTORE Namespace: mcn-sample +[STARTED] Date: 2024-02-21 07:09:50 UTC Tenant: f5xc-testdrive TASK: RESTORE Namespace: mcn-sample ==================================================================================================================================== [mcn-sample] Restoring Health Check object from file [ mcn-sample_healthcheck-mcn-sample-hc.json ] ..... DONE [mcn-sample] Restoring Origin Pool object from file [ mcn-sample_origin_pool-mcn-sample-originpool.json ] ..... DONE @@ -93,6 +90,6 @@ $ python3 f5xc-backup-restore.py -a restore -p /var/backup/f5xc-backup-20240221_ [mcn-sample] Restoring HTTP LoadBalancer object from file [ mcn-sample_http_lb-mcn-sample-lb.json ] ..... DONE [mcn-sample] Restoring Malicious User Policy object from file [ mcn-sample_malicioususer_policy-mcn-sample-maluser-policy.json ] ..... DONE ================================================================================================================ -[COMPLETED] Date: 2024-02-21 07:10:20 UTC Tenant: f5-xctestdrive +[COMPLETED] Date: 2024-02-21 07:10:20 UTC Tenant: f5xc-testdrive ================================================================================================================ ``` diff --git a/SECURITY.md b/SECURITY.md index de9e5ec..0ee240f 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -1,11 +1,45 @@ -## Security +# Security + +## Credentials + +The script will use credentials from an API Token to authenticate with the F5 Distributed Cloud API. The API Token is stored in a file called `config.ini` in the `.f5xc` directory. + +```bash +cd .f5xc +cat > config.ini<< EOF +[DEFAULT] +token=XXXXXXXX +tenant=f5xc-testdrive +EOF +``` + +The file should be readable only by the user running the script. + +```bash +chmod 600 .f5xc/config.ini +``` + +## Permissions + +The script should be run as a user with the minimum required permissions to perform the necessary operations. The user should have read and write permissions to the script, as well as read permissions to the backup directory. + +```bash +chown -R f5xc-service-account:f5xc-operations-group /path/to/script-output +chmod -R 750 /path/to/script-output +``` + +If additional users need to run the script, they should be added to the `f5xc-operations-group` group. + +```bash +usermod -a -G f5xc-operations-group additional-backup-user +``` + +## Reporting a Vulnerability The contributors to this project take security seriously. If you believe you have found a security vulnerability, please report it to as described below. -## Reporting a Vulnerability - **Please do not report security vulnerabilities through public GitHub issues.** Instead, please report any potential or current instances of security diff --git a/USAGE.md b/USAGE.md index d2cd1bb..69e12df 100644 --- a/USAGE.md +++ b/USAGE.md @@ -2,13 +2,16 @@ ### Configuration -Before running the script, you must create environment variables with your F5XC Tenant URL and API Token. +Before running the script, you must ensure you have your F5 Distributed Cloud tenant and API token store in the `config.ini` file in the `.f5xc` directory. ```bash - -export XC_API_TOKEN='XXXXXXXXX' -export XC_TENANT='f5-xctestdrive' - +mkdir .f5xc +cd .f5xc +cat > config.ini<< EOF +[DEFAULT] +token=XXXXXXXX +tenant=f5xc-testdrive +EOF ``` > [!NOTE]