deb/README.markdown

   1 # OpenDaylight Debian Packages
   2
   3 Logic for building OpenDaylight's upstream Debian packages.
   4
   5 #### Table of Contents
   6 1. [Overview](#overview)
   7 1. [Vagrant Build Environment](#vagrant-build-environment)
   8 1. [Building Debs](#building-debs)
   9 1. [Defining New Debs](#defining-new-debs)
  10   * [Deb Build Variables](#deb-build-variables)
  11 1. [Using Debs](#using-debs)
  12   * [Installing](#installing)
  13   * [Uninstalling](#uninstalling)
  14 1. [Using systemd](#using-systemd)
  15   * [Starting](#starting)
  16   * [Stopping](#stopping)
  17 1. [Karaf shell](#karaf-)
  18
  19 ## Overview
  20
  21 TODO: Overview of Debian pkg builds, plans
  22
  23 ## Vagrant Build Environment
  24
  25 Deb builds can be done in the included Vagrantfile. It provides a
  26 consistent, known-working and easily shared environment.
  27
  28     [~/packaging/deb]$ vagrant status
  29     Current machine states:
  30
  31     default                   not created (libvirt)
  32     [~/packaging/deb]$ vagrant up
  33     [~/packaging/deb]$ vagrant ssh
  34     [vagrant@localhost ~]$ ls /vagrant/
  35     opendaylight  README.markdown  Vagrantfile
  36
  37 ## Building Debs
  38
  39 The `build.py` helper script is used for building OpenDaylight .debs.
  40
  41 The `build.py` helper script can build a set of .debs based on provided
  42 version arguments.
  43
  44     [vagrant@localhost ~]$ /vagrant/build.py -h
  45     usage: build.py [-h] [-v [major minor patch deb [major minor patch deb ...]]]
  46     ....
  47
  48     optional arguments:
  49       -h, --help            show this help message and exit
  50
  51     Existing build:
  52       -v [major minor patch deb [major minor patch deb ...]], --version [major minor patch deb [major minor patch deb ...]]
  53                         Deb version(s) to build
  54     ....
  55
  56 The `-v`/`--version` flag accepts a version number. Any build that matches
  57 the portions provided will be built. If more than one build matches the
  58 portions provided, all matching builds will be executed.
  59
  60 For example, `build.py -v 3` would execute the builds that match the regex
  61 `3.*.*-*`. OpenDaylight 3.0.0-1 and 3.1.0-1, for example.
  62
  63 To only build a single debian package, provide enough version info to make
  64 the match unique. For example, `build.py -v 2 4 0 1` could only match one
  65 definition (Helium SR4, 2.4.0-1).
  66
  67 The `build.py` script uses `templates/build_debianfiles.py` to generate debian files for
  68 ODL .deb packages using JinJa2 templates and dynamic build data provided in `build_vars.yaml`.
  69
  70 ## Defining New Debs
  71
  72 The dynamic aspects of a build, such as ODL and Deb version info, have all
  73 been extracted to a single YAML configuration file. For most Deb updates,
  74 only that configuration file should need to be updated by humans.
  75
  76 The variables available for configuration are documented below. A build
  77 definition should define all supported variables.
  78
  79 ### Deb Build Variables
  80
  81 #### `version_major`
  82
  83 The OpenDaylight major (element) version number of the release to build.
  84
  85 For example, Hydrogen is 1.x.x, Helium is 2.x.x, Lithium is 3.x.x and
  86 so on down the periodic table.
  87
  88 #### `version_minor`
  89
  90 The OpenDaylight minor (SR) version number of the release to build.
  91
  92 #### `version_patch`
  93
  94 The OpenDaylight patch version of the release to build.
  95
  96 #### `pkg_version`
  97
  98 Debian revision for the given ODL major.minor.patch version.
  99
 100 In addition to OpenDaylight's version, .debs themselves have versions. These
 101 are called "debian revisions". For a given OpenDaylight major.minor.patch
 102 version, there will be one or more major.minor.patch-pkg_version .debs.
 103
 104 #### `sysd_commit`
 105
 106 Version of ODL systemd unitfile to download and package in ODL .deb.
 107
 108 The version of OpenDaylight's systemd unitfile, specified by the
 109 git commit hash, is downloaded from the [Int/Pack repo][16] and
 110 consumed by OpenDaylight's Deb builds.
 111
 112 #### `codename`
 113
 114 Elemental codename for the ODL release, including SR if applicable.
 115
 116 Examples include "Helium-SR4", "Lithium" and "Lithium-SR1".
 117
 118 #### `download_url`
 119
 120 The ODL Deb repackages the tarball build artifact produced by ODL's
 121 autorelease build. This is the URL to the tarball ODL build to repackage
 122 into a Debian package.
 123
 124 #### `java_version`
 125
 126 Java dependency for specific ODL builds
 127
 128 #### `changelog`
 129
 130 Entry in the debian/changelog file for specific .deb.
 131
 132 A debian/changelog file for specialized ODL builds is generated using these entries.
 133
 134 The changelog entry must follow a specific format. It's best to follow the
 135 examples provided by existing build definitions closely.
 136
 137 ## Using Debs
 138
 139 The familiar Deb-related commands apply to OpenDaylight's Debs.
 140
 141 ### Installing
 142
 143 To install a local OpenDaylight .deb package and resolve its dependencies, use `sudo gdebi <path to ODL .deb>`
 144
 145 Here's a walk-through of an install and the resulting system changes.
 146
 147     # Note that there's nothing in /opt before the install
 148     [vagrant@localhost vagrant]$ ls /opt/
 149     # Note that there are no ODL systemd files before the install
 150     [vagrant@localhost vagrant]$ ls /lib/systemd/system | grep -i opendaylight
 151     # Install an ODL .deb package
 152     [vagrant@localhost vagrant]$ sudo gdebi opendaylight/opendaylight_0.4.2-Beryllium-SR2-0_amd64.deb
 153     # Note that ODL is now installed in /opt
 154     [vagrant@localhost vagrant]$ ls /opt/
 155     opendaylight
 156     # Note that there's now a systemd .service file for ODL
 157     [vagrant@localhost vagrant]$ ls /lib/systemd/system | grep -i opendaylight
 158     opendaylight.service
 159
 160 ### Uninstalling
 161
 162 To uninstall a local OpenDaylight .deb package, use sudo apt-get remove opendaylight
 163
 164 Here's a walk-through of the uninstall and the resulting system changes.
 165
 166     # Note that ODL is installed in /opt/
 167     [vagrant@localhost vagrant]$ ls /opt/
 168     opendaylight
 169     # Note that there's a systemd .service file for ODL
 170     [vagrant@localhost vagrant]$ ls /lib/systemd/system | grep -i opendaylight
 171     opendaylight.service
 172     # Uninstall the ODL .deb package
 173     [vagrant@localhost vagrant]$ sudo apt-get remove opendaylight
 174     # Note that ODL user data has not been removed from /opt/
 175     [vagrant@localhost vagrant]$ ls /opt/opendaylight/
 176     data  instances
 177     # Uninstall the ODL .deb package and delete user data and configuration
 178     [vagrant@localhost vagrant]$ sudo apt-get purge opendaylight
 179     # Note that ODL has been completely removed from /opt/
 180     [vagrant@localhost vagrant]$ ls /opt/
 181     # Note that the ODL systemd .service file has been removed
 182     [vagrant@localhost vagrant]$ ls /lib/systemd/system | grep -i opendaylight
 183
 184 ## Using systemd
 185
 186 OpenDaylight's debs ship with systemd support.
 187
 188 ### Starting
 189
 190     [vagrant@localhost ~]$ sudo systemctl start opendaylight
 191     [vagrant@localhost ~]$ sudo systemctl status opendaylight
 192     ● opendaylight.service - OpenDaylight SDN Controller
 193        Loaded: loaded (/lib/systemd/system/opendaylight.service; enabled)
 194        Active: active (running) since Tue 2016-08-02 17:33:29 GMT; 2min 7s ago
 195          Docs: https://wiki.opendaylight.org/view/Main_Page
 196                http://www.opendaylight.org/
 197       Process: 1181 ExecStart=/opt/opendaylight/bin/start (code=exited, status=0/SUCCESS)
 198      Main PID: 1188 (java)
 199        CGroup: /system.slice/opendaylight.service
 200                └─1188 /usr/bin/java -Djava.security.properties=/opt/opendaylight/etc/odl.java.security -server -Xms128M -Xmx2048m -XX:+UnlockDiagnosticVMOptions -XX:+Unsy...
 201
 202 ### Stopping
 203
 204     [vagrant@localhost ~]$ sudo systemctl stop opendaylight
 205     [vagrant@localhost ~]$ sudo systemctl status OpenDaylight
 206     ● opendaylight.service - OpenDaylight SDN Controller
 207        Loaded: loaded (/lib/systemd/system/opendaylight.service; enabled)
 208        Active: inactive (dead) since Tue 2016-08-02 17:39:02 GMT; 10s ago
 209          Docs: https://wiki.opendaylight.org/view/Main_Page
 210                http://www.opendaylight.org/
 211       Process: 1181 ExecStart=/opt/opendaylight/bin/start (code=exited, status=0/SUCCESS)
 212      Main PID: 1188 (code=exited, status=143)
 213
 214 ## Karaf shell
 215
 216 A few seconds after OpenDaylight is started, its Karaf shell will be accessible.
 217
 218 You can connect by SSHing into ODL's karaf port and logging in (karaf/karaf).
 219
 220     [vagrant@localhost ~]$ ssh -p 8101 karaf@localhost
 221     Password authentication
 222     Password:
 223
 224         ________                       ________                .__  .__       .__     __
 225         \_____  \ ______   ____   ____ \______ \ _____  ___.__.|  | |__| ____ |  |___/  |
 226          /   |   \\____ \_/ __ \ /    \ |    |  \\__  \<   |  ||  | |  |/ ___\|  |  \   __\
 227         /    |    \  |_> >  ___/|   |  \|    `   \/ __ \\___  ||  |_|  / /_/  >   Y  \  |
 228         \_______  /   __/ \___  >___|  /_______  (____  / ____||____/__\___  /|___|  /__|
 229                 \/|__|        \/     \/        \/     \/\/            /_____/      \/
 230
 231
 232     Hit '<tab>' for a list of available commands
 233     and '[cmd] --help' for help on a specific command.
 234     Hit '<ctrl-d>' or type 'system:shutdown' or 'logout' to shutdown OpenDaylight.
 235
 236     opendaylight-user@root>
 237