From 1599bdad52611f7d549351a85676f5c565e4860d Mon Sep 17 00:00:00 2001 From: Tlams Date: Tue, 1 May 2018 11:33:33 +0100 Subject: [PATCH] Update doc --- README.md | 331 +++++---------------------------------- README2.md | 54 ------- README_OLD.md | 308 ++++++++++++++++++++++++++++++++++++ doc/md/04-configs.md | 4 +- doc/md/05-first_start.md | 4 +- doc/md/06-logs.md | 30 ++++ doc/md/07-api.md | 68 ++++++++ doc/md/08-usages.md | 54 +++++++ 8 files changed, 502 insertions(+), 351 deletions(-) delete mode 100644 README2.md create mode 100644 README_OLD.md diff --git a/README.md b/README.md index fe8df33..e6a37f6 100644 --- a/README.md +++ b/README.md @@ -1,308 +1,55 @@ # HyperProxmox +HyperProxmox provides a centralized platform for managing your Proxmox environments. +The web based client lets you manage the essential functions of your Proxmox infrastructure from any browser, +offering more responsiveness and usability than ever before. +Gain the visibility and control needed for your virtual machines, hosts and datastore. +Assign users to custom roles, search in inventory or provision new virtual machines at the click of a button. + * Author : [ThomasGSP](https://www.thomasgsp.fr) * Date : 2017/2018 * Version : Alpha 1.0 * Status: Dev -* Object : Massive LXC CT / KVM deployment and management system for Proxmox clusters. +* Object : Massive LXC CT / KVM deployment, management and viewer system for Proxmox clusters. +* Proxmox version supported: 3.x/4.x/5.x * Information : This project is currently in active development. You shouldn't use in production mode or... use at your risks ! -* Proxmox version supported: 3.x/4.x/5/x +### This version provide: +- Web interface to list instances, nodes and clusters +- Current usage (cpu / ram / disks...) for your nodes, instances... +- Quick usage visualisation by color (Green for low, yellow, red) +- Node scoring based on their usage +- Infrastructure historic +- Instance management (stop/start/restart...) +- Search system by VM-name, mac address ... +- Proxmox crawler (Getting cluster information) +- Security : Encipher the critical data (cluster access) +- LDAP authentication for web interface +- Group & cluster viewing in web interface +- Api -## Version informations: -* Provide: - - Basic web interface to list instances, nodes and clusters - - Basic instance management (stop/start/restart...) - - Data crawler - - API - - Encipher the critical data (cluster access) - - LDAP authentication for web interface - - Group & cluster viewing in web interface +### Weak on this version (in progress): +- Logs system +- Purge system +- Auto-generation MongoDB indexes (performance) +- Crawler work without parallel tasks (can be a bit slow on large infrastructure) -* In progress: - - Advanced logs system - - Purge old data - -* Not provide: - - Advanced security **(Not API authentication - DO NOT EXPOSE API WITHOUT AN AUTHENTICATION PROXY)** - - Instance deployment - - Lot of others things +### This version don't provide (next features): +- Advanced management +- Provision new virtual machines +- ... -## Requirement: -* Proxmox infrastructure (standalone, clusters...) - * Administrative pve user (full access) - -* MongoDB server - * Version 3.6 - * Standalone or with replicats for hight availability - -* Redis server - -* Web stack - * Nginx - * PHP7 - * php-curl, php7.0-json - -* Python softwares - * Version 3.5+ - * python-redis - * pymongo - * web.py - * python-requests - * Crypto +# Documentation +* [Prerequisites](doc/md/01-prerequisites.md) +* [Setup - Backend](doc/md/02-backend.md) +* [Setup - Frontend](doc/md/03-frontend.md) +* [Setup - Configs](doc/md/04-configs.md) +* [Usage - First start](doc/md/05-first_start.md) +* [Usage - Logs system](doc/md/06-logs.md) +* [Usage - API](doc/md/06-api.md) +* [Usage - Web interface](doc/md/08-usages.md) -## Installation (Debian type - Full standalone stack) -### Install all packages -``` bash -apt-get install php-fpm php-curl php-json python3-pip python3-redis python3-netaddr mongodb nginx redis-server git -pip3 install pymongo db utils web.py requests -``` - -### Configurations (bases) - -#### NGINX -``` bash -server { - listen *:443 ssl; - server_name youdomain.name; - root /var/www/hyperproxmox; - - ssl on; - ssl_certificate /etc/nginx/ssl/nginx.crt; - ssl_certificate_key /etc/nginx/ssl/nginx.key; - ssl_protocols TLSv1 TLSv1.1 TLSv1.2; - ssl_ciphers HIGH:!aNULL:!eNULL:!EXPORT:!CAMELLIA:!DES:!MD5:!PSK:!RC4; - ssl_prefer_server_ciphers on; - add_header Strict-Transport-Security "max-age=86400"; - - location ~ \.php$ { - include snippets/fastcgi-php.conf; - fastcgi_pass unix:/var/run/php-www.sock; - } -} - -``` -#### PHP -``` bash -[www] - -user = www-data -group = www-data - -listen = /var/run/php-www.sock -listen.owner = www-data -listen.group = www-data -listen.mode = 0660 - -pm = dynamic -pm.start_servers = 5 -pm.min_spare_servers = 5 -pm.max_spare_servers = 35 -pm.max_children = 50 - -pm.max_requests = 200 - -pm.status_path = /fpm-status -ping.path = /ping -ping.response = pong - -request_slowlog_timeout = 0 - -request_terminate_timeout = 0 -catch_workers_output = yes - -``` - -#### Hyperproxmox -``` bash -useradd hyperproxmox -cd /opt/ && git clone https://github.com/ThomasGsp/HyperProxmox.git - -# set www dir -mkdir /var/www/hyperproxmox -cp -R /opt/HyperProxmox/code/web/www/* /var/www/hyperproxmox/ -chown www-data: -R /var/www/hyperproxmox -# No www-data write (useless) -chmod 550 -R /var/www/hyperproxmox - -# Set hyperproxmox -chown hyperproxmox: -R /opt/HyperProxmox -chmod 760 -R /opt/HyperProxmox - -# Log dir (you can change it) -mkdir /var/log/hyperproxmox/ -chown hyperproxmox: /var/log/hyperproxmox/ - -#Rm demo keys -rm /opt/HyperProxmox/code/scripts/main/private/keys/Ragnarok.p* -``` - -``` bash -# Configurations -vi /opt/HyperProxmox/code/scripts/main/private/conf/config -< set your values > -``` - -#### Purge system -You should setup an cron to purge old data. -``` bash -RET=4 # older than the current date less this delay in days -DATETIMESTAMP=$(($(date +%s)-$((86400*$RET)))) -curl -H -XPOST -d '{ "action": "purge", "type":"strict", "date": $DATETIMESTAMP }' localhost:8080/api/v1/administration/purge -``` -* action: actiontype (only purge currently available) -* type: purge type (strict = all data before a date) -* date: delete data before this date - in seconds(timestamp) - - -### Init: -``` bash -# Start & generate your key (root user/sudo) -runuser -l hyperproxmox -c '/usr/bin/python3.5 /opt/HyperProxmox/code/scripts/main/startup.py' - -OUTPUT: -###################### -No key found, auto-generation started ... -Need a passphrase to start the generation: -This action can take some minutes, please wait. -Your new key has been generate ! - - Private Key: private/keys/Ragnarok.pvt.key - - Public Key: private/keys/Ragnarok.pvt.key -Passphrase HASH: 10e06b990d44de0091a2(......)5591c161ecc35944fc69c4433a49d10fc6b04a33611 -You MUST save your passphrase hash in a security place ! -Start API server... -http://127.0.0.1:8080/ -###################### -``` -The HASH will be ask at each start. -Without it, the privite key can be read and the access cannot be load in the memory. -If you loose it, you must delete the keys, delete the different entries in the collection "clusters_conf" in mongoDB database. - - -### Insert your first cluster (from host) -``` bash -# Minimum: -curl -H -XPOST -d '{ - "name": "Cluster_name", - "url":"proxmox.cluster.net", - "port": "8006", - "user": "user@pve", - "password": "******", - "template": "", - "storage_disk": "", - "exclude_nodes": [""], - "groups" : [""], - "weight": 1 - }' localhost:8080/api/v1/administration/cluster - -# Other example: -curl -H -XPOST -d '{ - "name": "Cluster_name", - "url":"proxmox.cluster.net", - "port": "8006", - "user": "user@pve", - "password": "******", - "template": "local:vztmpl/debian-9.0-standard_9.0-2_amd64.tar.gz", - "storage_disk": "disks", - "exclude_nodes": ["node_shit1"], - "groups" : ["group1", "group2..."], - "weight": 1 - }' localhost:8080/api/v1/administration/cluster - -``` - -* "name": Symbolic cluster name. Should be uniq (string) [VALUE NOT EMPTY REQUIRED] -* "url": Proxmox - Web GUI URL access (string) [VALUE NOT EMPTY REQUIRED] -* "port": Proxmox - Web PORT access (string) [VALUE NOT EMPTY REQUIRED] -* "user": Proxmox - Administrative PVE user (string) [VALUE NOT EMPTY REQUIRED] -* "password": Proxmox - PVE password (string) [VALUE NOT EMPTY REQUIRED] -* "template": Default template for LXC (string) -* "storage_disk": Default shared disk for KVM/LXC (string) -* "exclude_nodes": Do not use this nodes - Not visible (list) -* "groups" : Symbolics groups for this node (list) -* "weight": Weight for the cluster auto-selection (int) [VALUE NOT EMPTY REQUIRED] - - -![alt text](https://github.com/ThomasGsp/HyperProxmox/blob/master/doc/screenshots/h-nodes.jpg) -![alt text](https://github.com/ThomasGsp/HyperProxmox/blob/master/doc/screenshots/h-vms.jpg) -![alt text](https://github.com/ThomasGsp/HyperProxmox/blob/master/doc/screenshots/h-sto.jpg) - - - -## API Information - -### General informations - -### Instance status management -``` bash -'/api/v1/instance/id//status/(start|stop|current|reset|shutdown)' | GET -``` - -### Cluster management -``` bash -'/api/v1/administration/cluster/' | GET - Return the informations for an specific cluster - | PUT - Update the configurations for an specific cluster - | DELETE - Delete the configuration for an specific cluster - - -'/api/v1/administration/cluster' | GET - Return all clusters information - | POST - Insert a new cluster -``` - -### Data -``` bash -'/api/v1/administration/purge' | POST - Delete old data -``` - -### Cache Data - MongoDB -This data are manage by the crawler, you can't insert or change data yourself -``` bash -# date/cluster/node/vmid -# Disks mapping -'/api/v1/static/disks////' | GET - Return the informations for an specific disk -'/api/v1/static/disks////' | GET - Return all disks used in a node -'/api/v1/static/disks///' | GET - Return all disks used in a cluster -'/api/v1/static/disks//' | GET - Return all disks - -# Storages mapping -'/api/v1/static/storages////' | GET - Return all storage used in a node -'/api/v1/static/storages///' | GET - Return all storages used in a cluster -'/api/v1/static/storages//' | GET - Return all storages - -# Instances mapping -'/api/v1/static/instances////' | GET - Return the informations for an specific instance -'/api/v1/static/instances////' | GET - Return all instances for a node -'/api/v1/static/instances///' | GET - Return all instances for a cluster -'/api/v1/static/instances//' | GET - Return all instances (the dump can be very big, in a large infrastructure) - -# Nodes mapping -'/api/v1/static/nodes///' | GET - Return the informations for an specific node -'/api/v1/static/nodes///' | GET - Return all nodes for a cluster -'/api/v1/static/nodes//' | GET - Return all nodes - -# cluster mapping -'/api/v1/static/clusters//' | GET - Return the insformations for a specific cluster -'/api/v1/static/clusters//' | GET - Return all cluster informations - -# date -'/api/v1/static/dates/(all|last)' | GET - Return all or the last date available (generated by the crawler) - -# mongoid -'/api/v1/static/(instances|nodes|clusters|storages|disks)/id/' | GET - Return an information by mongoid - -``` - -### Typical use -``` bash -curl http://127.0.0.1:8080/api/v1/static/nodes/1519040226/Cluster_1/sd-817348 -``` - -## Unique ID -When a new instance is discover, the system assign an unique ID for this VM. -This unique ID is visible in the comments part in Proxmox. -This ID allow the possibility to follow the VM in a large infrastructure with frequent VM balancing between the Proxmox hypervisors. - diff --git a/README2.md b/README2.md deleted file mode 100644 index d8b1a18..0000000 --- a/README2.md +++ /dev/null @@ -1,54 +0,0 @@ -# HyperProxmox - -HyperProxmox provides a centralized platform for managing your Proxmox environments. -The web based client lets you manage the essential functions of your Proxmox infrastructure from any browser, -offering more responsiveness and usability than ever before. -Gain the visibility and control needed for your virtual machines, hosts and datastore. -Assign users to custom roles, search in inventory or provision new virtual machines at the click of a button. - -* Author : [ThomasGSP](https://www.thomasgsp.fr) -* Date : 2017/2018 -* Version : Alpha 1.0 -* Status: Dev -* Object : Massive LXC CT / KVM deployment, management and viewer system for Proxmox clusters. -* Proxmox version supported: 3.x/4.x/5.x -* Information : -This project is currently in active development. -You shouldn't use in production mode or... use at your risks ! - -### This version provide: -- Web interface to list instances, nodes and clusters -- Current usage (cpu / ram / disks...) for your nodes, instances... -- Quick usage visualisation by color (Green for low, yellow, red) -- Node scoring based on their usage -- Infrastructure historic -- Instance management (stop/start/restart...) -- Search system by VM-name, mac address ... -- Proxmox crawler (Getting cluster information) -- Security : Encipher the critical data (cluster access) -- LDAP authentication for web interface -- Group & cluster viewing in web interface -- Api - -### Weak on this version (in progress): -- Logs system -- Purge system -- Crawler work without parallel tasks (can be a bit slow on large infrastructure) - -### This version don't provide (next features): -- Advanced management -- Provision new virtual machines -- ... - -# Documentation -* [Prerequisites](doc/md/01-prerequisites.md) -* [Setup - Backend](doc/md/02-backend.md) -* [Setup - Frontend](doc/md/03-frontend.md) -* [Setup - Configs](doc/md/04-configs.md) -* [Usage - First start](doc/md/05-first_start.md) -* [Usage - Logs system](doc/md/06-logs.md) -* [Usage - API](doc/md/06-api.md) -* [Usage - Web interface](doc/md/08-usages.md) - - - diff --git a/README_OLD.md b/README_OLD.md new file mode 100644 index 0000000..fe8df33 --- /dev/null +++ b/README_OLD.md @@ -0,0 +1,308 @@ +# HyperProxmox + +* Author : [ThomasGSP](https://www.thomasgsp.fr) +* Date : 2017/2018 +* Version : Alpha 1.0 +* Status: Dev +* Object : Massive LXC CT / KVM deployment and management system for Proxmox clusters. +* Information : +This project is currently in active development. +You shouldn't use in production mode or... use at your risks ! + +* Proxmox version supported: 3.x/4.x/5/x + +## Version informations: +* Provide: + - Basic web interface to list instances, nodes and clusters + - Basic instance management (stop/start/restart...) + - Data crawler + - API + - Encipher the critical data (cluster access) + - LDAP authentication for web interface + - Group & cluster viewing in web interface + +* In progress: + - Advanced logs system + - Purge old data + +* Not provide: + - Advanced security **(Not API authentication - DO NOT EXPOSE API WITHOUT AN AUTHENTICATION PROXY)** + - Instance deployment + - Lot of others things + +## Requirement: +* Proxmox infrastructure (standalone, clusters...) + * Administrative pve user (full access) + +* MongoDB server + * Version 3.6 + * Standalone or with replicats for hight availability + +* Redis server + +* Web stack + * Nginx + * PHP7 + * php-curl, php7.0-json + +* Python softwares + * Version 3.5+ + * python-redis + * pymongo + * web.py + * python-requests + * Crypto + + + +## Installation (Debian type - Full standalone stack) +### Install all packages +``` bash +apt-get install php-fpm php-curl php-json python3-pip python3-redis python3-netaddr mongodb nginx redis-server git +pip3 install pymongo db utils web.py requests +``` + +### Configurations (bases) + +#### NGINX +``` bash +server { + listen *:443 ssl; + server_name youdomain.name; + root /var/www/hyperproxmox; + + ssl on; + ssl_certificate /etc/nginx/ssl/nginx.crt; + ssl_certificate_key /etc/nginx/ssl/nginx.key; + ssl_protocols TLSv1 TLSv1.1 TLSv1.2; + ssl_ciphers HIGH:!aNULL:!eNULL:!EXPORT:!CAMELLIA:!DES:!MD5:!PSK:!RC4; + ssl_prefer_server_ciphers on; + add_header Strict-Transport-Security "max-age=86400"; + + location ~ \.php$ { + include snippets/fastcgi-php.conf; + fastcgi_pass unix:/var/run/php-www.sock; + } +} + +``` +#### PHP +``` bash +[www] + +user = www-data +group = www-data + +listen = /var/run/php-www.sock +listen.owner = www-data +listen.group = www-data +listen.mode = 0660 + +pm = dynamic +pm.start_servers = 5 +pm.min_spare_servers = 5 +pm.max_spare_servers = 35 +pm.max_children = 50 + +pm.max_requests = 200 + +pm.status_path = /fpm-status +ping.path = /ping +ping.response = pong + +request_slowlog_timeout = 0 + +request_terminate_timeout = 0 +catch_workers_output = yes + +``` + +#### Hyperproxmox +``` bash +useradd hyperproxmox +cd /opt/ && git clone https://github.com/ThomasGsp/HyperProxmox.git + +# set www dir +mkdir /var/www/hyperproxmox +cp -R /opt/HyperProxmox/code/web/www/* /var/www/hyperproxmox/ +chown www-data: -R /var/www/hyperproxmox +# No www-data write (useless) +chmod 550 -R /var/www/hyperproxmox + +# Set hyperproxmox +chown hyperproxmox: -R /opt/HyperProxmox +chmod 760 -R /opt/HyperProxmox + +# Log dir (you can change it) +mkdir /var/log/hyperproxmox/ +chown hyperproxmox: /var/log/hyperproxmox/ + +#Rm demo keys +rm /opt/HyperProxmox/code/scripts/main/private/keys/Ragnarok.p* +``` + +``` bash +# Configurations +vi /opt/HyperProxmox/code/scripts/main/private/conf/config +< set your values > +``` + +#### Purge system +You should setup an cron to purge old data. +``` bash +RET=4 # older than the current date less this delay in days +DATETIMESTAMP=$(($(date +%s)-$((86400*$RET)))) +curl -H -XPOST -d '{ "action": "purge", "type":"strict", "date": $DATETIMESTAMP }' localhost:8080/api/v1/administration/purge +``` +* action: actiontype (only purge currently available) +* type: purge type (strict = all data before a date) +* date: delete data before this date - in seconds(timestamp) + + +### Init: +``` bash +# Start & generate your key (root user/sudo) +runuser -l hyperproxmox -c '/usr/bin/python3.5 /opt/HyperProxmox/code/scripts/main/startup.py' + +OUTPUT: +###################### +No key found, auto-generation started ... +Need a passphrase to start the generation: +This action can take some minutes, please wait. +Your new key has been generate ! + - Private Key: private/keys/Ragnarok.pvt.key + - Public Key: private/keys/Ragnarok.pvt.key +Passphrase HASH: 10e06b990d44de0091a2(......)5591c161ecc35944fc69c4433a49d10fc6b04a33611 +You MUST save your passphrase hash in a security place ! +Start API server... +http://127.0.0.1:8080/ +###################### +``` +The HASH will be ask at each start. +Without it, the privite key can be read and the access cannot be load in the memory. +If you loose it, you must delete the keys, delete the different entries in the collection "clusters_conf" in mongoDB database. + + +### Insert your first cluster (from host) +``` bash +# Minimum: +curl -H -XPOST -d '{ + "name": "Cluster_name", + "url":"proxmox.cluster.net", + "port": "8006", + "user": "user@pve", + "password": "******", + "template": "", + "storage_disk": "", + "exclude_nodes": [""], + "groups" : [""], + "weight": 1 + }' localhost:8080/api/v1/administration/cluster + +# Other example: +curl -H -XPOST -d '{ + "name": "Cluster_name", + "url":"proxmox.cluster.net", + "port": "8006", + "user": "user@pve", + "password": "******", + "template": "local:vztmpl/debian-9.0-standard_9.0-2_amd64.tar.gz", + "storage_disk": "disks", + "exclude_nodes": ["node_shit1"], + "groups" : ["group1", "group2..."], + "weight": 1 + }' localhost:8080/api/v1/administration/cluster + +``` + +* "name": Symbolic cluster name. Should be uniq (string) [VALUE NOT EMPTY REQUIRED] +* "url": Proxmox - Web GUI URL access (string) [VALUE NOT EMPTY REQUIRED] +* "port": Proxmox - Web PORT access (string) [VALUE NOT EMPTY REQUIRED] +* "user": Proxmox - Administrative PVE user (string) [VALUE NOT EMPTY REQUIRED] +* "password": Proxmox - PVE password (string) [VALUE NOT EMPTY REQUIRED] +* "template": Default template for LXC (string) +* "storage_disk": Default shared disk for KVM/LXC (string) +* "exclude_nodes": Do not use this nodes - Not visible (list) +* "groups" : Symbolics groups for this node (list) +* "weight": Weight for the cluster auto-selection (int) [VALUE NOT EMPTY REQUIRED] + + +![alt text](https://github.com/ThomasGsp/HyperProxmox/blob/master/doc/screenshots/h-nodes.jpg) +![alt text](https://github.com/ThomasGsp/HyperProxmox/blob/master/doc/screenshots/h-vms.jpg) +![alt text](https://github.com/ThomasGsp/HyperProxmox/blob/master/doc/screenshots/h-sto.jpg) + + + +## API Information + +### General informations + +### Instance status management +``` bash +'/api/v1/instance/id//status/(start|stop|current|reset|shutdown)' | GET +``` + +### Cluster management +``` bash +'/api/v1/administration/cluster/' | GET - Return the informations for an specific cluster + | PUT - Update the configurations for an specific cluster + | DELETE - Delete the configuration for an specific cluster + + +'/api/v1/administration/cluster' | GET - Return all clusters information + | POST - Insert a new cluster +``` + +### Data +``` bash +'/api/v1/administration/purge' | POST - Delete old data +``` + +### Cache Data - MongoDB +This data are manage by the crawler, you can't insert or change data yourself +``` bash +# date/cluster/node/vmid +# Disks mapping +'/api/v1/static/disks////' | GET - Return the informations for an specific disk +'/api/v1/static/disks////' | GET - Return all disks used in a node +'/api/v1/static/disks///' | GET - Return all disks used in a cluster +'/api/v1/static/disks//' | GET - Return all disks + +# Storages mapping +'/api/v1/static/storages////' | GET - Return all storage used in a node +'/api/v1/static/storages///' | GET - Return all storages used in a cluster +'/api/v1/static/storages//' | GET - Return all storages + +# Instances mapping +'/api/v1/static/instances////' | GET - Return the informations for an specific instance +'/api/v1/static/instances////' | GET - Return all instances for a node +'/api/v1/static/instances///' | GET - Return all instances for a cluster +'/api/v1/static/instances//' | GET - Return all instances (the dump can be very big, in a large infrastructure) + +# Nodes mapping +'/api/v1/static/nodes///' | GET - Return the informations for an specific node +'/api/v1/static/nodes///' | GET - Return all nodes for a cluster +'/api/v1/static/nodes//' | GET - Return all nodes + +# cluster mapping +'/api/v1/static/clusters//' | GET - Return the insformations for a specific cluster +'/api/v1/static/clusters//' | GET - Return all cluster informations + +# date +'/api/v1/static/dates/(all|last)' | GET - Return all or the last date available (generated by the crawler) + +# mongoid +'/api/v1/static/(instances|nodes|clusters|storages|disks)/id/' | GET - Return an information by mongoid + +``` + +### Typical use +``` bash +curl http://127.0.0.1:8080/api/v1/static/nodes/1519040226/Cluster_1/sd-817348 +``` + +## Unique ID +When a new instance is discover, the system assign an unique ID for this VM. +This unique ID is visible in the comments part in Proxmox. +This ID allow the possibility to follow the VM in a large infrastructure with frequent VM balancing between the Proxmox hypervisors. + diff --git a/doc/md/04-configs.md b/doc/md/04-configs.md index 9e56f30..c995b6f 100644 --- a/doc/md/04-configs.md +++ b/doc/md/04-configs.md @@ -124,10 +124,10 @@ DATETIMESTAMP=$(($(date +%s)-$((86400*$RET)))) * type: purge type (strict = all data before this date) * date: delete data before this date - in seconds(timestamp) -Currently, just one mod is available: stric. +Currently, just one mod is available: strict. It's mean that ALL data will be delete before the date. Some others possibility should be available in the future, like keep one day per week. -[Frontend](03-frontend.md) <-- Previous | Next --> [Usage - First start](05-first_start.md) +[Setup - Frontend](03-frontend.md) <-- Previous | Next --> [Usage - First start](05-first_start.md) diff --git a/doc/md/05-first_start.md b/doc/md/05-first_start.md index 63a3808..6cf00be 100644 --- a/doc/md/05-first_start.md +++ b/doc/md/05-first_start.md @@ -30,6 +30,4 @@ If you loose it, you must delete the keys and delete the different entries in th Currently there are not system to provide a full reset function. Use MongoDB shell to do it. - - -[Config](04-configs.md) <-- Previous | Next --> [Usage - Logs](05-first_start.md) +[Setup - Config](04-configs.md) <-- Previous | Next --> [Usage - Logs](05-first_start.md) diff --git a/doc/md/06-logs.md b/doc/md/06-logs.md index e69de29..1a1307a 100644 --- a/doc/md/06-logs.md +++ b/doc/md/06-logs.md @@ -0,0 +1,30 @@ +# Logs + +A log system is available, but not complete. + +Format: [DATE] [THREAD_ID] [LEVEL] [TYPE] : JSON-DATA +* DATE = When the log is generated. (If bulk system is activate, date is respected) +* THREAD_ID = Hyperproxmox work with different thread (Core, API, crawler, sub-crawler...). If you wan debug correctly, you can use +grep to follow your thread. +* LEVEL = WARNING, INFO, DEBUG... +* TYPE = Who generate this log + +Log example: +```bash +[2018-04-29 15:59] [140273766102784] [ERROR] [HYPERPROXMOX] : +{ +"target": "my.promoxserver.com:8006", +"result": "ERROR", " +value": "Cannot get ticket session my.promoxserver.com:8006 (HTTPSConnectionPool(host='my.promoxserver.com:8006', port=8006): Max retries exceeded with url: /api2/json/access/ticket?username=***YOUR_USER***&password=***PWD***(Caused by ConnectTimeoutError(, 'Connection to my.promoxserver.com:8006 timed out. (connect timeout=5)')))", +"type": "PYTHON" +} +``` + +This log show a bad connection to Proxmox server. + +User and password are hidden: +```bash +username=***YOUR_USER***&password=***PWD*** +``` + +[Usage - First start](05-first_start.md) <-- Previous | Next --> [Usage - API](07-api.md) \ No newline at end of file diff --git a/doc/md/07-api.md b/doc/md/07-api.md index e69de29..8873431 100644 --- a/doc/md/07-api.md +++ b/doc/md/07-api.md @@ -0,0 +1,68 @@ +# API Information + +### Instance status management +``` bash +'/api/v1/instance/id//status/(start|stop|current|reset|shutdown)' | GET +``` + +### Cluster management +``` bash +'/api/v1/administration/cluster/' | GET - Return the informations for an specific cluster + | PUT - Update the configurations for an specific cluster + | DELETE - Delete the configuration for an specific cluster + + +'/api/v1/administration/cluster' | GET - Return all clusters information + | POST - Insert a new cluster +``` + +### Data +``` bash +'/api/v1/administration/purge' | POST - Delete old data +``` + +### Cache Data - MongoDB +This data are manage by the crawler, you can't insert or change data yourself +``` bash +# date/cluster/node/vmid +# Disks mapping +'/api/v1/static/disks////' | GET - Return the informations for an specific disk +'/api/v1/static/disks////' | GET - Return all disks used in a node +'/api/v1/static/disks///' | GET - Return all disks used in a cluster +'/api/v1/static/disks//' | GET - Return all disks + +# Storages mapping +'/api/v1/static/storages////' | GET - Return all storage used in a node +'/api/v1/static/storages///' | GET - Return all storages used in a cluster +'/api/v1/static/storages//' | GET - Return all storages + +# Instances mapping +'/api/v1/static/instances////' | GET - Return the informations for an specific instance +'/api/v1/static/instances////' | GET - Return all instances for a node +'/api/v1/static/instances///' | GET - Return all instances for a cluster +'/api/v1/static/instances//' | GET - Return all instances (the dump can be very big, in a large infrastructure) + +# Nodes mapping +'/api/v1/static/nodes///' | GET - Return the informations for an specific node +'/api/v1/static/nodes///' | GET - Return all nodes for a cluster +'/api/v1/static/nodes//' | GET - Return all nodes + +# cluster mapping +'/api/v1/static/clusters//' | GET - Return the insformations for a specific cluster +'/api/v1/static/clusters//' | GET - Return all cluster informations + +# date +'/api/v1/static/dates/(all|last)' | GET - Return all or the last date available (generated by the crawler) + +# mongoid +'/api/v1/static/(instances|nodes|clusters|storages|disks)/id/' | GET - Return an information by mongoid + +``` + +### Typical use +``` bash +curl http://127.0.0.1:8080/api/v1/static/nodes/1519040226/Cluster_1/sd-817348 +``` + + +[Usage - logs](06-logs.md) <-- Previous | Next --> [Usage - General](08-usages.md) \ No newline at end of file diff --git a/doc/md/08-usages.md b/doc/md/08-usages.md index e69de29..a1f44b3 100644 --- a/doc/md/08-usages.md +++ b/doc/md/08-usages.md @@ -0,0 +1,54 @@ +# Usages + +## API + +Insert your first cluster (from host) +``` bash +# Minimum: +curl -H -XPOST -d '{ + "name": "Cluster_name", + "url":"proxmox.cluster.net", + "port": "8006", + "user": "user@pve", + "password": "******", + "template": "", + "storage_disk": "", + "exclude_nodes": [""], + "groups" : [""], + "weight": 1 + }' localhost:8080/api/v1/administration/cluster + +# Other example: +curl -H -XPOST -d '{ + "name": "Cluster_name", + "url":"proxmox.cluster.net", + "port": "8006", + "user": "user@pve", + "password": "******", + "template": "local:vztmpl/debian-9.0-standard_9.0-2_amd64.tar.gz", + "storage_disk": "disks", + "exclude_nodes": ["node_shit1"], + "groups" : ["group1", "group2..."], + "weight": 1 + }' localhost:8080/api/v1/administration/cluster + +``` + +* "name": Symbolic cluster name. Should be uniq (string) [VALUE NOT EMPTY REQUIRED] +* "url": Proxmox - Web GUI URL access (string) [VALUE NOT EMPTY REQUIRED] +* "port": Proxmox - Web PORT access (string) [VALUE NOT EMPTY REQUIRED] +* "user": Proxmox - Administrative PVE user (string) [VALUE NOT EMPTY REQUIRED] +* "password": Proxmox - PVE password (string) [VALUE NOT EMPTY REQUIRED] +* "template": Default template for LXC (string) +* "storage_disk": Default shared disk for KVM/LXC (string) +* "exclude_nodes": Do not use this nodes - Not visible (list) +* "groups" : Symbolics groups for this node (list) +* "weight": Weight for the cluster auto-selection (int) [VALUE NOT EMPTY REQUIRED] + + +![alt text](https://github.com/ThomasGsp/HyperProxmox/blob/master/doc/screenshots/h-nodes.jpg) +![alt text](https://github.com/ThomasGsp/HyperProxmox/blob/master/doc/screenshots/h-vms.jpg) +![alt text](https://github.com/ThomasGsp/HyperProxmox/blob/master/doc/screenshots/h-sto.jpg) + + +[Usage - api](07-api.md) <-- Previous \ No newline at end of file