README.dev

   1 = Setup PVE Development Environment =
   2
   3 1. Install Debian 'jessie'
   4 2. Configure pvetest repository in apt sources.list
   5
   6  deb http://download.proxmox.com/debian jessie pvetest
   7
   8 3. Add our repository key with apt-key:
   9
  10  wget -O- "http://download.proxmox.com/debian/key.asc" | apt-key add -
  11
  12 4. make sure you have a read IP address for your hostname in /etc/hosts
  13    (using 127.0.1.1 will not work)
  14
  15 5. run: apt-get update
  16 6. run: apt-get dist-upgrade
  17 7. run: apt-get install proxmox-ve-3.10.0
  18
  19 You should now have a working Proxmox VE installation.
  20
  21 = Install build prerequisites for development environment =
  22
  23 apt-get -y install build-essential git-core debhelper autotools-dev \
  24 autogen dh-autoreconf dkms doxygen check pkg-config groff quilt dpatch \
  25 automake autoconf libtool lintian libdevel-cycle-perl libjson-perl \
  26 libcommon-sense-perl liblinux-inotify2-perl libio-stringy-perl \
  27 libstring-shellquote-perl dh-systemd rpm2cpio libsqlite3-dev sqlite3 \
  28 libglib2.0-dev librrd-dev librrds-perl rrdcached libdigest-hmac-perl \
  29 libxml-parser-perl gdb libcrypt-openssl-random-perl \
  30 libcrypt-openssl-rsa-perl libnet-ldap-perl libauthen-pam-perl \
  31 libjson-xs-perl libterm-readline-gnu-perl oathtool libmime-base32-perl \
  32 liboath0 libpci-dev texi2html libsdl1.2-dev libgnutls28-dev \
  33 libspice-protocol-dev xfslibs-dev libnuma-dev libaio-dev \
  34 pve-libspice-server-dev libusbredirparser-dev glusterfs-common \
  35 libusb-1.0-0-dev librbd-dev libpopt-dev iproute bridge-utils numactl \
  36 glusterfs-common ceph-common python-ceph libgoogle-perftools4 \
  37 libfile-chdir-perl lvm2 glusterfs-client liblockfile-simple-perl \
  38 libsystemd-daemon-dev libreadline-gplv2-dev libio-multiplex-perl \
  39 libnetfilter-log-dev libipset3 ipset socat libsasl2-dev libogg-dev \
  40 python-pyparsing libfilesys-df-perl libcrypt-ssleay-perl \
  41 libfile-readbackwards-perl libanyevent-perl libanyevent-http-perl \
  42 unzip liblocale-po-perl vlan ifenslave-2.6 libfile-sync-perl cstream \
  43 lzop dtach apt-transport-https hdparm gdisk parted ttf-dejavu-core \
  44 liblzma-dev dosfstools mtools libxen-dev libfuse-dev libcorosync-pve-dev \
  45 libqb-dev
  46
  47 = Compile PVE packages from Source =
  48
  49 Download and install the following git modules in order from top to bottom:
  50
  51 # git clone git://git.proxmox.com/git/<PACKAGE.git>
  52
  53 You currently need the following packages:
  54
  55 libqb.git
  56 corosync-pve.git
  57 pve-common.git
  58 pve-cluster.git
  59 lvm.git
  60 pve-access-control.git
  61 pve-storage.git
  62 pve-qemu-kvm.git
  63 qemu-server.git
  64 vncterm.git
  65 spiceterm.git
  66 #vzquota.git
  67 #vzctl.git
  68 #fence-agents-pve.git
  69 #resource-agents-pve.git
  70 pve-manager.git
  71 pve-kernel-3.10.0.git
  72 libiscsi.git
  73 #gfs2-utils.git
  74 ksm-control-daemon.git
  75
  76 Most packages can be installed with 'make dinstall' command.
  77
  78 4.  Reboot the system.
  79 5.  Learn to use the quilt patch scripts.
  80 6.  Happy coding.
  81
  82 There is an experimental package containing the API documentation
  83 as ExtJS application:
  84
  85 pve2-api-doc.git
  86
  87 You can view the source code at:
  88
  89 https://git.proxmox.com
  90
  91
  92 = REST vs. SOAP =
  93
  94 We decided to change our SOAP API (1.X) and use a REST like API. The
  95 concept is described in [1] (Resource Oriented Architecture
  96 (ROA)). The main advantage is that we are able to remove a lot of code
  97 (the whole SOAP stack) to reduce software complexity.
  98
  99 We also moved away from server side content generation. Instead we use
 100 the ExtJS Rich Internet Application Framework
 101 (http://www.sencha.com).
 102
 103 That framework, like any other AJAX toolkit, can talk directly to the
 104 REST API using JSON. So we were able to remove the server side
 105 template toolkit completely.
 106
 107 = JSON and JSON Schema =
 108
 109 We use JSON as data format, because it is simple and parse-able by any
 110 web browser.
 111
 112 Additionally, we use JSON Schema [2] to formally describe our API. So
 113 we can automatically generate the whole API Documentation, and we can
 114 verify all parameters and return values.
 115
 116 A great side effect was that we are able to use JSON Schema to
 117 produce command line argument parsers automatically. In fact, the REST
 118 API and the command line tools use the same code.
 119
 120 Object linkage is done using the JSON Hyper Schema (links property).
 121
 122 A small utility called 'pvesh' exposes the whole REST API on the command
 123 line.
 124
 125 So here is a summary of the advantage:
 126
 127    - easy, human readable data format (native web browser format)
 128    - automatic parameter verification (we can also verify return values)
 129    - automatic generation of API documentation
 130    - easy way to create command line tools (using same API).
 131
 132 = API Implementation (PVE::RESTHandler) =
 133
 134 All classes exposing methods on the API use PVE::RESTHandler as base class.
 135
 136   use base qw(PVE::RESTHandler);
 137
 138 To expose methods, one needs to call register_method():
 139
 140   __PACKAGE__->register_method ($schema);
 141
 142 Where $schema is a PVE method schema as described in
 143 PVE::JSONSchema. It includes a description of parameters and return
 144 values, and a reference to the actual code
 145
 146 __PACKAGE__->register_method ({
 147     name => 'echo',
 148     path => 'echo',
 149     method => 'GET',
 150     description => "simple return value of parameter 'text'",
 151     parameters => {
 152         additionalProperties => 0,
 153         properties => {
 154             text => {
 155                  type => 'string',
 156             }
 157         },
 158     },
 159     returns => {
 160         type => 'string',
 161     },
 162     code => sub {
 163         my ($conn, $resp, $param) = @_;
 164
 165         return $param->{text};
 166     }
 167 });
 168
 169 The 'name' property is only used if you want to call the method
 170 directly from Perl. You can do that using:
 171
 172   print __PACKAGE__->echo({ text => "a test" });
 173
 174 We use Perl's AUTOLOAD feature to implement this. Note: You need to
 175 pass parameters a HASH reference.
 176
 177 There is a special helper method called cli_handler(). This is used by
 178 the CLIHandler Class for command line tools, where you want to pass
 179 arguments as array of strings. This uses Getopt::Long to parse parameters.
 180
 181 There is a second way to map names to methods - using the 'path'
 182 property.  And you can register subclasses. That way you can set up a
 183 filesystem like hierarchy to access methods.
 184
 185 Here is an example:
 186 ----------------------------
 187 package C1;
 188
 189 __PACKAGE__->register_method ({
 190     subclass => "C2",
 191     path => 'sub2',
 192 });
 193
 194
 195 __PACKAGE__->register_method ({
 196     name => 'list1',
 197     path => 'index',
 198     method => 'GET',
 199     ...
 200 });
 201
 202 package C2;
 203
 204 __PACKAGE__->register_method ({
 205     name => 'list2',
 206     path => 'index',
 207     method => 'GET',
 208     ...
 209 });
 210 -------------------------------
 211
 212 The utily method find_handler (in PVE::RESTHandler) can be use to do
 213 'path' related method lookups.
 214
 215 C1->find_handler('GET', "/index")      => C1::list1
 216 C1->find_handler('GET', "/sub2/index") => C2::list2
 217
 218 The HTTP server use the URL (a path) to find the corresponding method.
 219
 220
 221 = References =
 222
 223 [1] RESTful Web Services
 224 Web services for the real world
 225
 226 By
 227     Leonard Richardson, Sam Ruby
 228 Publisher:
 229     O'Reilly Media
 230 Released:
 231     May 2007
 232
 233 [2] JSON Schema links: http://json-schema.org/