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
  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 git-email debhelper \
  24 autotools-dev autogen dh-autoreconf dkms doxygen check pkg-config \
  25 groff quilt dpatch automake autoconf libtool lintian libdevel-cycle-perl \
  26 libjson-perl 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-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 corosync-dev \
  45 libcpg-dev libquorum-dev libcmap-dev libuuid-perl \
  46 libqb-dev libapparmor-dev docbook2x libcap-dev dh-apparmor \
  47 graphviz libseccomp-dev libglib-perl libgtk3-perl libnss3-dev libdlm-dev \
  48 libudev-dev asciidoc-dblatex source-highlight inkscape
  49
  50 = Compile PVE packages from Source =
  51
  52 Download and install the following git modules in order from top to bottom:
  53
  54 # git clone git://git.proxmox.com/git/<PACKAGE.git>
  55
  56 You currently need the following packages:
  57
  58 pve-common.git
  59 libpve-http-server-perl.git
  60 libpve-apiclient-perl.git
  61 pve-docs.git
  62 pve-cluster.git
  63 lvm.git
  64 pve-access-control.git
  65 pve-storage.git
  66 pve-qemu-kvm.git
  67 qemu-server.git
  68 vncterm.git
  69 spiceterm.git
  70 #vzquota.git
  71 #vzctl.git
  72 #fence-agents-pve.git
  73 #resource-agents-pve.git
  74 pve-manager.git
  75 #pve-kernel-3.10.0.git
  76 #libiscsi.git
  77 #gfs2-utils.git
  78 ksm-control-daemon.git
  79 pve-container.git
  80 pve-firewall.git
  81 pve-kernel.git
  82
  83 Most packages can be installed with 'make dinstall' command.
  84
  85 4.  Reboot the system.
  86 5.  Learn to use the quilt patch scripts.
  87 6.  Happy coding.
  88
  89 There is an experimental package containing the API documentation
  90 as ExtJS application:
  91
  92 pve2-api-doc.git
  93
  94 You can view the source code at:
  95
  96 https://git.proxmox.com
  97
  98
  99 = REST vs. SOAP =
 100
 101 We decided to change our SOAP API (1.X) and use a REST like API. The
 102 concept is described in [1] (Resource Oriented Architecture
 103 (ROA)). The main advantage is that we are able to remove a lot of code
 104 (the whole SOAP stack) to reduce software complexity.
 105
 106 We also moved away from server side content generation. Instead we use
 107 the ExtJS Rich Internet Application Framework
 108 (http://www.sencha.com).
 109
 110 That framework, like any other AJAX toolkit, can talk directly to the
 111 REST API using JSON. So we were able to remove the server side
 112 template toolkit completely.
 113
 114 = JSON and JSON Schema =
 115
 116 We use JSON as data format, because it is simple and parse-able by any
 117 web browser.
 118
 119 Additionally, we use JSON Schema [2] to formally describe our API. So
 120 we can automatically generate the whole API Documentation, and we can
 121 verify all parameters and return values.
 122
 123 A great side effect was that we are able to use JSON Schema to
 124 produce command line argument parsers automatically. In fact, the REST
 125 API and the command line tools use the same code.
 126
 127 Object linkage is done using the JSON Hyper Schema (links property).
 128
 129 A small utility called 'pvesh' exposes the whole REST API on the command
 130 line.
 131
 132 So here is a summary of the advantage:
 133
 134    - easy, human readable data format (native web browser format)
 135    - automatic parameter verification (we can also verify return values)
 136    - automatic generation of API documentation
 137    - easy way to create command line tools (using same API).
 138
 139 = API Implementation (PVE::RESTHandler) =
 140
 141 All classes exposing methods on the API use PVE::RESTHandler as base class.
 142
 143   use base qw(PVE::RESTHandler);
 144
 145 To expose methods, one needs to call register_method():
 146
 147   __PACKAGE__->register_method ($schema);
 148
 149 Where $schema is a PVE method schema as described in
 150 PVE::JSONSchema. It includes a description of parameters and return
 151 values, and a reference to the actual code
 152
 153 __PACKAGE__->register_method ({
 154     name => 'echo',
 155     path => 'echo',
 156     method => 'GET',
 157     description => "simple return value of parameter 'text'",
 158     parameters => {
 159         additionalProperties => 0,
 160         properties => {
 161             text => {
 162                  type => 'string',
 163             }
 164         },
 165     },
 166     returns => {
 167         type => 'string',
 168     },
 169     code => sub {
 170         my ($param) = @_;
 171
 172         return $param->{text};
 173     }
 174 });
 175
 176 The 'name' property is only used if you want to call the method
 177 directly from Perl. You can do that using:
 178
 179   print __PACKAGE__->echo({ text => "a test" });
 180
 181 We use Perl's AUTOLOAD feature to implement this. Note: You need to
 182 pass parameters a HASH reference.
 183
 184 There is a special helper method called cli_handler(). This is used by
 185 the CLIHandler Class for command line tools, where you want to pass
 186 arguments as array of strings. This uses Getopt::Long to parse parameters.
 187
 188 There is a second way to map names to methods - using the 'path'
 189 property.  And you can register subclasses. That way you can set up a
 190 filesystem like hierarchy to access methods.
 191
 192 Here is an example:
 193 ----------------------------
 194 package C1;
 195
 196 __PACKAGE__->register_method ({
 197     subclass => "C2",
 198     path => 'sub2',
 199 });
 200
 201
 202 __PACKAGE__->register_method ({
 203     name => 'list1',
 204     path => 'index',
 205     method => 'GET',
 206     ...
 207 });
 208
 209 package C2;
 210
 211 __PACKAGE__->register_method ({
 212     name => 'list2',
 213     path => 'index',
 214     method => 'GET',
 215     ...
 216 });
 217 -------------------------------
 218
 219 The utily method find_handler (in PVE::RESTHandler) can be use to do
 220 'path' related method lookups.
 221
 222 C1->find_handler('GET', "/index")      => C1::list1
 223 C1->find_handler('GET', "/sub2/index") => C2::list2
 224
 225 The HTTP server use the URL (a path) to find the corresponding method.
 226
 227
 228 = References =
 229
 230 [1] RESTful Web Services
 231 Web services for the real world
 232
 233 By
 234     Leonard Richardson, Sam Ruby
 235 Publisher:
 236     O'Reilly Media
 237 Released:
 238     May 2007
 239
 240 [2] JSON Schema links: http://json-schema.org/