fog-proxmox 0.13.0

data/docs/connection_parameters.md

@@ -0,0 +1,45 @@
+# Optional connection parameters
+
+Fog supports passing additional connection parameters to its underlying HTTP library (Excon) using the `:connection_options` parameter.
+
+<table>
+	<tr>
+		<th>Key</th>
+		<th>Description</th>
+	</tr>
+	<tr>
+		<td>:connect_timeout</td>
+		<td>Connection timeout (default: 60 seconds)</td>
+	</tr>
+	<tr>
+		<td>:read_timeout</td>
+		<td>Read timeout for connection (default: 60 seconds)</td>	</tr>
+	<tr>
+		<td>:write_timeout</td>
+		<td>Write timeout for connection (default: 60 seconds)</td>
+	</tr>
+	<tr>
+		<td>:proxy</td>
+		<td>Proxy for HTTP and HTTPS connections</td>
+	</tr>
+	<tr>
+		<td>:ssl_ca_path</td>
+		<td>Path to SSL certificate authorities</td>
+	</tr>
+	<tr>
+		<td>:ssl_ca_file</td>
+		<td>SSL certificate authority file</td>
+	</tr>
+	<tr>
+		<td>:ssl_verify_peer</td>
+		<td>SSL verify peer (default: true)</td>
+	</tr>
+  <tr>
+    <td>:debug_request</td>
+    <td>debug print request (default: false)</td>
+  </tr>
+  <tr>
+    <td>:debug_response</td>
+    <td>debug print response (default: false)</td>
+  </tr>
+</table>

data/docs/getting_started.md

@@ -0,0 +1,53 @@
+# Getting started with Fog proxmox
+
+## Requirements
+
+### Ruby
+
+2.3, 2.4 and 2.5 ruby versions are tested and required.
+Fog requires 2.0+ for new projects.
+
+## Installation
+
+With rubygems:
+
+```ruby
+gem install fog-proxmox
+```
+
+With bundler:
+
+Create a Gemfile with:
+
+```ruby
+source 'https://rubygems.org'
+
+gem 'fog-proxmox'
+```
+
+then:
+
+```ruby
+bundler install
+```
+
+## Exploring capabilities
+
+```ruby
+irb
+```
+
+```ruby
+require 'fog/proxmox'
+```
+
+```ruby
+Fog::Proxmox.services
+```
+
+This command show you a summary of the available services.
+
+### Available services in details
+
+* [Identity](identity.md)
+* [Compute](compute.md)

data/docs/identity.md

@@ -0,0 +1,357 @@
+# Identity
+
+This document shows you the identity service (or user management) available with fog-proxmox.
+
+Proxmox supports many authentication sources (PAM, LDAP, Active Directory) and an authorization management (ACL, privileges).
+
+You can see more details in [Proxmox user management wiki page](https://pve.proxmox.com/wiki/User_Management)
+
+## Starting irb console
+
+```ruby
+irb
+```
+
+```ruby
+require 'fog/proxmox'
+```
+
+## Create identity service
+
+```ruby
+identity = Fog::Proxmox::Identity.new(
+        pve_username: PVE_USERNAME, # your user name
+        pve_password: PVE_PASSWORD, # your password
+        pve_url: PVE_URL, # your server url
+		connection_options: {} # connection options
+)
+```
+
+[connection_options](connection_parameters.md) are also available.
+
+## Fog Abstractions
+
+Fog provides both a **model** and **request** abstraction. The request abstraction provides the most efficient interface and the model abstraction wraps the request abstraction to provide a convenient `ActiveModel` like interface.
+
+### Request Layer
+
+The request abstraction maps directly to the [Proxmox VE API](https://pve.proxmox.com/wiki/Proxmox_VE_API). It provides an interface to the Proxmox Identity service.
+
+To see a list of requests supported by the identity service:
+
+```ruby
+identity.requests
+```
+
+To learn more about Identity request methods refer to source files.
+
+To learn more about Excon refer to [Excon GitHub repo](https://github.com/geemus/excon).
+
+### Model Layer
+
+Fog models behave in a manner similar to `ActiveModel`. Models will generally respond to `create`, `save`,  `persisted?`, `destroy`, `reload` and `attributes` methods. Additionally, fog will automatically create attribute accessors.
+
+Here is a summary of common model methods:
+
+<table>
+	<tr>
+		<th>Method</th>
+		<th>Description</th>
+	</tr>
+	<tr>
+		<td>create</td>
+		<td>
+			Accepts hash of attributes and creates object.<br>
+			Note: creation is a non-blocking call and you will be required to wait for a valid state before using resulting object.
+		</td>
+	</tr>
+	<tr>
+		<td>update</td>
+		<td>Updates object.<br>
+		Note: not all objects support updating object.</td>
+	</tr>
+	<tr>
+		<td>destroy</td>
+		<td>
+			Destroys object.<br>
+			Note: this is a non-blocking call and object deletion might not be instantaneous.
+		</td>
+	<tr>
+		<td>attributes</td>
+		<td>Returns a hash containing the list of model attributes and values.</td>
+	</tr>
+		<td>identity</td>
+		<td>
+			Returns the identity of the object.<br>
+			Note: This might not always be equal to object.id.
+		</td>
+	</tr>
+</table>
+
+The remainder of this document details the model abstraction.
+
+#### Users management
+
+List all users:
+
+```ruby
+identity.users.all
+```
+
+This returns a collection of `Fog::Proxmox::Identity::User` models:
+
+Create a user:
+
+```ruby
+identity.users.create({
+    userid: 'bobsinclar@pve',
+    password: 'bobsinclar1',
+    firstname: 'Bob',
+    lastname: 'Sinclar',
+    email: 'bobsinclar@proxmox.com'
+})
+```
+
+Get a user:
+
+```ruby
+user = identity.users.find_by_id 'bobsinclar@pve'
+```
+
+Change his password:
+
+```ruby
+user.password = 'bobsinclar2'
+user.change_password
+```
+
+Add groups to user:
+
+```ruby
+user.groups = %w[group1 group2]
+user.update
+```
+
+Delete user:
+
+```ruby
+user.destroy
+```
+
+#### Groups management
+
+Proxmox supports permissions management by group.
+
+Proxmox recommends to manage permissions by group instead of by user.
+
+List all groups:
+
+```ruby
+identity.groups.all
+```
+
+This returns a collection of `Fog::Proxmox::Identity::Group` models:
+
+Create a group:
+
+```ruby
+identity.groups.create({
+    groupid: 'group1'
+})
+```
+
+Get a group:
+
+```ruby
+group = identity.groups.find_by_id 'group1'
+```
+
+Add a comment:
+
+```ruby
+group.comment = 'Group 1'
+group.update
+```
+
+Delete group:
+
+```ruby
+group.destroy
+```
+
+#### Domains management
+
+Proxmox supports 4 domains or realms (sources of authentication): PAM, PVE, LDAP and Active Directory.
+
+Proxmox server has two default domains: PAM and PVE.
+
+List all domains:
+
+```ruby
+identity.domains.all
+```
+
+This returns a collection of `Fog::Proxmox::Identity::Domain` models:
+
+Create a LDAP domain:
+
+```ruby
+identity.domains.create({
+        realm: 'LDAP',
+        type: 'ldap',
+        base_dn: 'ou=People,dc=ldap-test,dc=com',
+        user_attr: 'LDAP',
+        server1: 'localhost',
+        port: 389,
+        default: 0,
+        secure: 0
+      })
+```
+
+Get a domain:
+
+```ruby
+ldap = identity.domains.find_by_id 'LDAP'
+```
+
+Add a comment and a two factor authentication (OATH) to LDAP realm:
+
+```ruby
+ldap.type.comment = 'Test domain LDAP'
+ldap.type.tfa = 'type=oath,step=30,digits=8'
+ldap.update
+```
+
+Delete domain:
+
+```ruby
+ldap.destroy
+```
+
+#### Roles management
+
+Proxmox supports roles management to give permissions to group of users.
+
+Proxmox server has several defaults roles already created. See [Proxmox user management wiki page](https://pve.proxmox.com/wiki/User_Management)
+
+List all roles:
+
+```ruby
+identity.roles.all
+```
+
+This returns a collection of `Fog::Proxmox::Identity::Role` models:
+
+Create a new role:
+
+```ruby
+identity.roles.create({ roleid: 'PVETestAuditor' })
+```
+
+Get the role:
+
+```ruby
+role = identity.groups.find_by_id 'PVETestAuditor'
+```
+
+Add privileges to this new role:
+
+```ruby
+role.privs = 'Datastore.Audit Sys.Audit VM.Audit'
+role.update
+```
+
+List of all available privileges can be seen at [Proxmox user management wiki page](https://pve.proxmox.com/wiki/User_Management)
+
+Delete role:
+
+```ruby
+role.destroy
+```
+
+#### Permissions management
+
+Proxmox supports permissions management. Access permissions are assigned to objects, such as a virtual machines, storages or pools of resources. It uses path to identify these objects. Path is the same as REST API path.
+
+See more details in [Proxmox user management wiki page](https://pve.proxmox.com/wiki/User_Management)
+
+List all permissions:
+
+```ruby
+identity.permissions.all
+```
+
+This returns a collection of `Fog::Proxmox::Identity::Permission` models:
+
+Add a new permission (manage users) to a user:
+
+```ruby
+identity.permissions.add({
+    path: '/access/users',
+    roles: 'PVEUserAdmin',
+    users: 'bobsinclar@pve'
+})
+```
+
+Add a new permission (manage users) to a group of users:
+
+```ruby
+identity.permissions.add({
+    path: '/access/users',
+    roles: 'PVEUserAdmin',
+    groups: 'group1'
+})
+```
+
+Remove a permission to a user:
+
+```ruby
+identity.permissions.remove({
+    path: '/access/users',
+    roles: 'PVEUserAdmin',
+    users: 'bobsinclar@pve'
+})
+```
+#### Pools management
+
+Proxmox supports pools management of VMs or storages. It eases managing permissions on these.
+
+Create a pool:
+
+```ruby
+identity.pools.create { poolid: 'pool1' }
+```
+
+Get a pool:
+
+```ruby
+pool1 = identity.pools.find_by_id 'pool1'
+```
+
+Add comment, server 100 and storage local-lvm to the pool:
+
+```ruby
+pool1.comment = 'Pool 1'
+pool1.update
+pool1.add_server 100
+pool1.add_storage 'local-lvm '
+```
+
+Get all pools:
+
+```ruby
+identity.pools.all
+```
+
+Delete pool:
+
+```ruby
+# you need to remove all members before deleting pool
+pool1.remove_server 100
+pool1.remove_storage 'local-lvm '
+pool1.destroy
+```
+
+### Examples
+
+More examples can be seen at [examples/identity.rb](examples/identity.rb) or [spec/identity_spec.rb](spec/identity_spec.rb).