getting_started.rst 8.4 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232
  1. Getting Started
  2. ===============
  3. Selecting the right version
  4. ---------------------------
  5. Gluon's releases are managed using `Git tags`_. If you are just getting
  6. started with Gluon we recommend to use the latest stable release of Gluon.
  7. Take a look at the `list of gluon releases`_ and notice the latest release,
  8. e.g. *v2016.2.1*. Always get Gluon using git and don't try to download it
  9. as a Zip archive as the archive will be missing version information.
  10. Please keep in mind that there is no "default Gluon" build; a site configuration
  11. is required to adjust Gluon to your needs. Due to new features being added (or
  12. sometimes being removed) the format of the site configuration changes slightly
  13. between releases. Please refer to our release notes for instructions to update
  14. an old site configuration to a newer release of Gluon.
  15. An example configuration can be found in the Gluon repository at *docs/site-example/*.
  16. .. _Git tags: http://git-scm.com/book/en/Git-Basics-Tagging
  17. .. _list of gluon releases: https://github.com/freifunk-gluon/gluon/releases
  18. Dependencies
  19. ------------
  20. To build Gluon, several packages need to be installed on the system. On a
  21. freshly installed Debian Wheezy system the following packages are required:
  22. * `git` (to get Gluon and other dependencies)
  23. * `subversion`
  24. * `python` (Python 3 doesn't work)
  25. * `build-essential`
  26. * `gawk`
  27. * `unzip`
  28. * `libncurses-dev` (actually `libncurses5-dev`)
  29. * `libz-dev` (actually `zlib1g-dev`)
  30. * `libssl-dev`
  31. * `wget`
  32. Building the images
  33. -------------------
  34. To build Gluon, first check out the repository. Replace *RELEASE* with the
  35. version you'd like to checkout, e.g. *v2016.2.1*.
  36. ::
  37. git clone https://github.com/freifunk-gluon/gluon.git gluon -b RELEASE
  38. This command will create a directory named *gluon/*.
  39. It might also tell a scary message about being in a *detached state*.
  40. **Don't panic!** Everything's fine.
  41. Now, enter the freshly created directory::
  42. cd gluon
  43. It's time to add (or create) your site configuration. If you already
  44. have a site repository, just clone it::
  45. git clone https://github.com/freifunk-alpha-centauri/site-ffac.git site
  46. If you want to build a new site, create a new git repository *site/*::
  47. mkdir site
  48. cd site
  49. git init
  50. Copy *site.conf*, *site.mk* and *i18n* from *docs/site-example*::
  51. cp ../docs/site-example/site.conf .
  52. cp ../docs/site-example/site.mk .
  53. cp -r ../docs/site-example/i18n .
  54. Edit these files as you see fit and commit them into the site repository.
  55. Extensive documentation about the site configuration can be found at:
  56. :doc:`site`. The
  57. site directory should always be a git repository by itself; committing site-specific files
  58. to the Gluon main repository should be avoided, as it will make updates more complicated.
  59. Next go back to the top-level Gluon directory and build Gluon::
  60. cd ..
  61. make update # Get other repositories used by Gluon
  62. make GLUON_TARGET=ar71xx-generic # Build Gluon
  63. When calling make, the OpenWrt build environment is prepared/updated.
  64. In case of errors read the messages carefully and try to fix the stated issues (e.g. install tools not available yet).
  65. ``ar71xx-generic`` is the most common target and will generate images for most of the supported hardware.
  66. To see a complete list of supported targets, call ``make`` without setting ``GLUON_TARGET``.
  67. You should reserve about 10GB of disk space for each `GLUON_TARGET`.
  68. The built images can be found in the directory `output/images`. Of these, the `factory`
  69. images are to be used when flashing from the original firmware a device came with,
  70. and `sysupgrade` is to upgrade from other versions of Gluon or any other OpenWrt-based
  71. system.
  72. **Note:** The images for some models are identical; to save disk space, symlinks are generated instead
  73. of multiple copies of the same image. If your webserver's configuration prohibits following
  74. symlinks, you can use the following command to resolve these links while copying the images::
  75. cp -rL output/images /var/www
  76. Cleaning the build tree
  77. .......................
  78. There are two levels of `make clean`::
  79. make clean GLUON_TARGET=ar71xx-generic
  80. will ensure all packages are rebuilt for a single target; this is what you normally want to do after an update.
  81. ::
  82. make dirclean
  83. will clean the entire tree, so the toolchain will be rebuilt as well, which is
  84. not necessary in most cases, and will take a while.
  85. So in summary, to update and rebuild a Gluon build tree, the following commands should be used (repeat the
  86. ``make clean`` and ``make`` for all targets you want to build):
  87. ::
  88. git pull
  89. (cd site && git pull)
  90. make update
  91. make clean GLUON_TARGET=ar71xx-generic
  92. make GLUON_TARGET=ar71xx-generic
  93. opkg repositories
  94. -----------------
  95. Gluon is mostly compatible with OpenWrt, so the normal OpenWrt package repositories
  96. can be used for Gluon as well. It is advisable to setup a mirror or reverse proxy
  97. reachable over IPv6 and add it to ``site.conf`` as http://downloads.openwrt.org/ does
  98. not support IPv6.
  99. This is not true for kernel modules; the Gluon kernel is incompatible with the
  100. kernel of the default OpenWrt images. Therefore, Gluon will not only generate images,
  101. but also an opkg repository containing all kernel modules provided by OpenWrt/Gluon
  102. for the kernel of the generated images.
  103. Signing keys
  104. ............
  105. Gluon does not support HTTPS for downloading packages; fortunately, opkg deploys
  106. public-key cryptography to ensure package integrity.
  107. The Gluon images will contain two public keys: the official OpenWrt signing key
  108. (to allow installing userspace packages) and a Gluon-specific key (which is used
  109. to sign the generated module repository).
  110. By default, Gluon will handle the generation and handling of the keys itself.
  111. When making firmware releases based on Gluon, it might make sense to store
  112. the keypair, so updating the module repository later is possible.
  113. The location the keys are stored at and read from can be changed
  114. (see :ref:`getting-started-make-variables`). To only generate the keypair
  115. at the configured location without doing a full build, use ``make create-key``.
  116. .. _getting-started-make-variables:
  117. Make variables
  118. --------------
  119. Gluon's build process can be controlled by various variables. They can
  120. usually be set on the command line or in ``site.mk``.
  121. Common variables
  122. ................
  123. GLUON_ATH10K_MESH
  124. While Gluon does support some hardware with ath10k-based 5GHz WLAN, these WLAN adapters don't work
  125. well for meshing at the moment, so building images for these models is disabled by default. In addition,
  126. ath10k can't support IBSS and 11s meshing in the same image due to WLAN firmware restrictions.
  127. Setting GLUON_ATH10K_MESH to ``11s`` or ``ibss`` will enable generation of images for ath10k devices
  128. and install the firmware for the corresponding WLAN mode.
  129. GLUON_BRANCH
  130. Sets the default branch of the autoupdater. If unset, the autoupdater is disabled
  131. by default. For the ``make manifest`` command, GLUON_BRANCH defines the branch to
  132. generate a manifest for.
  133. GLUON_LANGS
  134. Space-separated list of languages to include for the config mode/advanced settings. Defaults to ``en``.
  135. ``en`` should always be included, other supported languages are ``de`` and ``fr``.
  136. GLUON_PRIORITY
  137. Defines the priority of an automatic update in ``make manifest``. See :doc:`../features/autoupdater` for
  138. a detailed description of this value.
  139. GLUON_REGION
  140. Some devices (at the moment the TP-Link Archer C7) contain a region code that restricts
  141. firmware installations. Set GLUON_REGION to ``eu`` or ``us`` to make the resulting
  142. images installable from the respective stock firmwares.
  143. GLUON_RELEASE
  144. Firmware release number: This string is displayed in the config mode, announced
  145. via respondd/alfred and used by the autoupdater to decide if a newer version
  146. is available.
  147. GLUON_TARGET
  148. Target architecture to build.
  149. Special variables
  150. .................
  151. GLUON_BUILDDIR
  152. Working directory during build. Defaults to ``build``.
  153. GLUON_IMAGEDIR
  154. Path where images will be stored. Defaults to ``$(GLUON_OUTPUTDIR)/images``.
  155. GLUON_MODULEDIR
  156. Path where the kernel module opkg repository will be stored. Defaults to ``$(GLUON_OUTPUTDIR)/modules``.
  157. GLUON_OPKG_KEY
  158. Path key file used to sign the module opkg repository. Defaults to ``$(GLUON_BULDDIR)/gluon-opkg-key``.
  159. The private key will be stored as ``$(GLUON_OPKG_KEY)``, the public key as ``$(GLUON_OPKG_KEY).pub``.
  160. GLUON_OUTPUTDIR
  161. Path where output files will be stored. Defaults to ``output``.
  162. GLUON_SITEDIR
  163. Path to the site configuration. Defaults to ``site``.