Revision c27d829e

b/.gitignore
3 3
*~
4 4
.dir
5 5
version.py
6
docs/_build
b/docs/Makefile
1
# Makefile for Sphinx documentation
2
#
3

  
4
# You can set these variables from the command line.
5
SPHINXOPTS    =
6
SPHINXBUILD   = sphinx-build
7
PAPER         =
8
BUILDDIR      = _build
9

  
10
# Internal variables.
11
PAPEROPT_a4     = -D latex_paper_size=a4
12
PAPEROPT_letter = -D latex_paper_size=letter
13
ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
14
# the i18n builder cannot share the environment and doctrees with the others
15
I18NSPHINXOPTS  = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
16

  
17
.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext
18

  
19
help:
20
	@echo "Please use \`make <target>' where <target> is one of"
21
	@echo "  html       to make standalone HTML files"
22
	@echo "  dirhtml    to make HTML files named index.html in directories"
23
	@echo "  singlehtml to make a single large HTML file"
24
	@echo "  pickle     to make pickle files"
25
	@echo "  json       to make JSON files"
26
	@echo "  htmlhelp   to make HTML files and a HTML help project"
27
	@echo "  qthelp     to make HTML files and a qthelp project"
28
	@echo "  devhelp    to make HTML files and a Devhelp project"
29
	@echo "  epub       to make an epub"
30
	@echo "  latex      to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
31
	@echo "  latexpdf   to make LaTeX files and run them through pdflatex"
32
	@echo "  text       to make text files"
33
	@echo "  man        to make manual pages"
34
	@echo "  texinfo    to make Texinfo files"
35
	@echo "  info       to make Texinfo files and run them through makeinfo"
36
	@echo "  gettext    to make PO message catalogs"
37
	@echo "  changes    to make an overview of all changed/added/deprecated items"
38
	@echo "  linkcheck  to check all external links for integrity"
39
	@echo "  doctest    to run all doctests embedded in the documentation (if enabled)"
40

  
41
clean:
42
	-rm -rf $(BUILDDIR)/*
43

  
44
html:
45
	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
46
	@echo
47
	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
48

  
49
dirhtml:
50
	$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
51
	@echo
52
	@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
53

  
54
singlehtml:
55
	$(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
56
	@echo
57
	@echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
58

  
59
pickle:
60
	$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
61
	@echo
62
	@echo "Build finished; now you can process the pickle files."
63

  
64
json:
65
	$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
66
	@echo
67
	@echo "Build finished; now you can process the JSON files."
68

  
69
htmlhelp:
70
	$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
71
	@echo
72
	@echo "Build finished; now you can run HTML Help Workshop with the" \
73
	      ".hhp project file in $(BUILDDIR)/htmlhelp."
74

  
75
qthelp:
76
	$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
77
	@echo
78
	@echo "Build finished; now you can run "qcollectiongenerator" with the" \
79
	      ".qhcp project file in $(BUILDDIR)/qthelp, like this:"
80
	@echo "# qcollectiongenerator $(BUILDDIR)/qthelp/nfdhcpd.qhcp"
81
	@echo "To view the help file:"
82
	@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/nfdhcpd.qhc"
83

  
84
devhelp:
85
	$(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp
86
	@echo
87
	@echo "Build finished."
88
	@echo "To view the help file:"
89
	@echo "# mkdir -p $$HOME/.local/share/devhelp/nfdhcpd"
90
	@echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/nfdhcpd"
91
	@echo "# devhelp"
92

  
93
epub:
94
	$(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub
95
	@echo
96
	@echo "Build finished. The epub file is in $(BUILDDIR)/epub."
97

  
98
latex:
99
	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
100
	@echo
101
	@echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
102
	@echo "Run \`make' in that directory to run these through (pdf)latex" \
103
	      "(use \`make latexpdf' here to do that automatically)."
104

  
105
latexpdf:
106
	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
107
	@echo "Running LaTeX files through pdflatex..."
108
	$(MAKE) -C $(BUILDDIR)/latex all-pdf
109
	@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
110

  
111
text:
112
	$(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text
113
	@echo
114
	@echo "Build finished. The text files are in $(BUILDDIR)/text."
115

  
116
man:
117
	$(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man
118
	@echo
119
	@echo "Build finished. The manual pages are in $(BUILDDIR)/man."
120

  
121
texinfo:
122
	$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
123
	@echo
124
	@echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo."
125
	@echo "Run \`make' in that directory to run these through makeinfo" \
126
	      "(use \`make info' here to do that automatically)."
127

  
128
info:
129
	$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
130
	@echo "Running Texinfo files through makeinfo..."
131
	make -C $(BUILDDIR)/texinfo info
132
	@echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo."
133

  
134
gettext:
135
	$(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale
136
	@echo
137
	@echo "Build finished. The message catalogs are in $(BUILDDIR)/locale."
138

  
139
changes:
140
	$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
141
	@echo
142
	@echo "The overview file is in $(BUILDDIR)/changes."
143

  
144
linkcheck:
145
	$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
146
	@echo
147
	@echo "Link check complete; look for any errors in the above output " \
148
	      "or in $(BUILDDIR)/linkcheck/output.txt."
149

  
150
doctest:
151
	$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
152
	@echo "Testing of doctests in the sources finished, look at the " \
153
	      "results in $(BUILDDIR)/doctest/output.txt."
b/docs/conf.py
1
# -*- coding: utf-8 -*-
2
#
3
# nfdhcpd documentation build configuration file, created by
4
# sphinx-quickstart on Mon Jan 20 18:25:17 2014.
5
#
6
# This file is execfile()d with the current directory set to its containing dir.
7
#
8
# Note that not all possible configuration values are present in this
9
# autogenerated file.
10
#
11
# All configuration values have a default; values that are commented out
12
# serve to show the default.
13

  
14
import sys, os
15

  
16
# If extensions (or modules to document with autodoc) are in another directory,
17
# add these directories to sys.path here. If the directory is relative to the
18
# documentation root, use os.path.abspath to make it absolute, like shown here.
19
#sys.path.insert(0, os.path.abspath('.'))
20

  
21
# -- General configuration -----------------------------------------------------
22

  
23
# If your documentation needs a minimal Sphinx version, state it here.
24
#needs_sphinx = '1.0'
25

  
26
# Add any Sphinx extension module names here, as strings. They can be extensions
27
# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
28
extensions = []
29

  
30
# Add any paths that contain templates here, relative to this directory.
31
templates_path = ['_templates']
32

  
33
# The suffix of source filenames.
34
source_suffix = '.rst'
35

  
36
# The encoding of source files.
37
#source_encoding = 'utf-8-sig'
38

  
39
# The master toctree document.
40
master_doc = 'index'
41

  
42
# General information about the project.
43
project = u'nfdhcpd'
44
copyright = u'2014, Dimitris Aragiorgis'
45

  
46
# The version info for the project you're documenting, acts as replacement for
47
# |version| and |release|, also used in various other places throughout the
48
# built documents.
49
#
50
# The short X.Y version.
51
version = '0.12'
52
# The full version, including alpha/beta/rc tags.
53
release = '0.12.0'
54

  
55
# The language for content autogenerated by Sphinx. Refer to documentation
56
# for a list of supported languages.
57
#language = None
58

  
59
# There are two options for replacing |today|: either, you set today to some
60
# non-false value, then it is used:
61
#today = ''
62
# Else, today_fmt is used as the format for a strftime call.
63
#today_fmt = '%B %d, %Y'
64

  
65
# List of patterns, relative to source directory, that match files and
66
# directories to ignore when looking for source files.
67
exclude_patterns = ['_build']
68

  
69
# The reST default role (used for this markup: `text`) to use for all documents.
70
#default_role = None
71

  
72
# If true, '()' will be appended to :func: etc. cross-reference text.
73
#add_function_parentheses = True
74

  
75
# If true, the current module name will be prepended to all description
76
# unit titles (such as .. function::).
77
#add_module_names = True
78

  
79
# If true, sectionauthor and moduleauthor directives will be shown in the
80
# output. They are ignored by default.
81
#show_authors = False
82

  
83
# The name of the Pygments (syntax highlighting) style to use.
84
pygments_style = 'sphinx'
85

  
86
# A list of ignored prefixes for module index sorting.
87
#modindex_common_prefix = []
88

  
89

  
90
# -- Options for HTML output ---------------------------------------------------
91

  
92
# The theme to use for HTML and HTML Help pages.  See the documentation for
93
# a list of builtin themes.
94
html_theme = 'default'
95

  
96
# Theme options are theme-specific and customize the look and feel of a theme
97
# further.  For a list of options available for each theme, see the
98
# documentation.
99
#html_theme_options = {}
100

  
101
# Add any paths that contain custom themes here, relative to this directory.
102
#html_theme_path = []
103

  
104
# The name for this set of Sphinx documents.  If None, it defaults to
105
# "<project> v<release> documentation".
106
#html_title = None
107

  
108
# A shorter title for the navigation bar.  Default is the same as html_title.
109
#html_short_title = None
110

  
111
# The name of an image file (relative to this directory) to place at the top
112
# of the sidebar.
113
#html_logo = None
114

  
115
# The name of an image file (within the static path) to use as favicon of the
116
# docs.  This file should be a Windows icon file (.ico) being 16x16 or 32x32
117
# pixels large.
118
#html_favicon = None
119

  
120
# Add any paths that contain custom static files (such as style sheets) here,
121
# relative to this directory. They are copied after the builtin static files,
122
# so a file named "default.css" will overwrite the builtin "default.css".
123
html_static_path = ['_static']
124

  
125
# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
126
# using the given strftime format.
127
#html_last_updated_fmt = '%b %d, %Y'
128

  
129
# If true, SmartyPants will be used to convert quotes and dashes to
130
# typographically correct entities.
131
#html_use_smartypants = True
132

  
133
# Custom sidebar templates, maps document names to template names.
134
#html_sidebars = {}
135

  
136
# Additional templates that should be rendered to pages, maps page names to
137
# template names.
138
#html_additional_pages = {}
139

  
140
# If false, no module index is generated.
141
#html_domain_indices = True
142

  
143
# If false, no index is generated.
144
#html_use_index = True
145

  
146
# If true, the index is split into individual pages for each letter.
147
#html_split_index = False
148

  
149
# If true, links to the reST sources are added to the pages.
150
#html_show_sourcelink = True
151

  
152
# If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
153
#html_show_sphinx = True
154

  
155
# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
156
#html_show_copyright = True
157

  
158
# If true, an OpenSearch description file will be output, and all pages will
159
# contain a <link> tag referring to it.  The value of this option must be the
160
# base URL from which the finished HTML is served.
161
#html_use_opensearch = ''
162

  
163
# This is the file name suffix for HTML files (e.g. ".xhtml").
164
#html_file_suffix = None
165

  
166
# Output file base name for HTML help builder.
167
htmlhelp_basename = 'nfdhcpddoc'
168

  
169

  
170
# -- Options for LaTeX output --------------------------------------------------
171

  
172
latex_elements = {
173
# The paper size ('letterpaper' or 'a4paper').
174
#'papersize': 'letterpaper',
175

  
176
# The font size ('10pt', '11pt' or '12pt').
177
#'pointsize': '10pt',
178

  
179
# Additional stuff for the LaTeX preamble.
180
#'preamble': '',
181
}
182

  
183
# Grouping the document tree into LaTeX files. List of tuples
184
# (source start file, target name, title, author, documentclass [howto/manual]).
185
latex_documents = [
186
  ('index', 'nfdhcpd.tex', u'nfdhcpd Documentation',
187
   u'Dimitris Aragiorgis', 'manual'),
188
]
189

  
190
# The name of an image file (relative to this directory) to place at the top of
191
# the title page.
192
#latex_logo = None
193

  
194
# For "manual" documents, if this is true, then toplevel headings are parts,
195
# not chapters.
196
#latex_use_parts = False
197

  
198
# If true, show page references after internal links.
199
#latex_show_pagerefs = False
200

  
201
# If true, show URL addresses after external links.
202
#latex_show_urls = False
203

  
204
# Documents to append as an appendix to all manuals.
205
#latex_appendices = []
206

  
207
# If false, no module index is generated.
208
#latex_domain_indices = True
209

  
210

  
211
# -- Options for manual page output --------------------------------------------
212

  
213
# One entry per manual page. List of tuples
214
# (source start file, name, description, authors, manual section).
215
man_pages = [
216
    ('index', 'nfdhcpd', u'nfdhcpd Documentation',
217
     [u'Dimitris Aragiorgis'], 1)
218
]
219

  
220
# If true, show URL addresses after external links.
221
#man_show_urls = False
222

  
223

  
224
# -- Options for Texinfo output ------------------------------------------------
225

  
226
# Grouping the document tree into Texinfo files. List of tuples
227
# (source start file, target name, title, author,
228
#  dir menu entry, description, category)
229
texinfo_documents = [
230
  ('index', 'nfdhcpd', u'nfdhcpd Documentation',
231
   u'Dimitris Aragiorgis', 'nfdhcpd', 'One line description of project.',
232
   'Miscellaneous'),
233
]
234

  
235
# Documents to append as an appendix to all manuals.
236
#texinfo_appendices = []
237

  
238
# If false, no module index is generated.
239
#texinfo_domain_indices = True
240

  
241
# How to display URL addresses: 'footnote', 'no', or 'inline'.
242
#texinfo_show_urls = 'footnote'
b/docs/index.rst
1
.. nfdhcpd documentation master file, created by
2
   sphinx-quickstart on Mon Jan 20 18:25:17 2014.
3
   You can adapt this file completely to your liking, but it should at least
4
   contain the root `toctree` directive.
5

  
6
Welcome to nfdhcpd's documentation!
7
===================================
8

  
9
nfdhcpd is a userspace server written in python and based on NFQUEUE [1].  The
10
administrator can enable processing of DHCP, NS, RS, DHCPv6 requests on
11
individual TAP interfaces by injecting nfdhcpd in the processing pipeline for
12
IP packets dynamically (by mangling the corresponding packet types and redirect
13
them to the appropriate nfqueue).
14

  
15
The daemon runs on the host and is controlled by manipulating files under its
16
state directory. Creation of a new file under this directory ("binding file")
17
instructs the daemon to reply on the requests arriving on the specified TAP
18
interface.
19

  
20
nfdhcpd vs. dnsmasq
21
-------------------
22

  
23
a) The service can be activated dynamically, per-interface, by manipulating
24
iptables accordingly. There is no need to restart the daemon, or edit
25
(potentially read-only) configuration files, you only need to drop a file
26
containing the required info under /var/lib/nfdhcpd.
27

  
28
b) There is no interference to existing DHCP servers listening to port
29
67. Everything happens directly via NFQUEUE.
30

  
31
c) The host doesn't even need to have an IP address on the interfaces
32
where DHCP replies are served, making it invisible to the VMs. This
33
may be beneficial from a security perspective. Similarly, it doesn't
34
matter if the TAP interface is bridged or routed.
35

  
36
d) Binding files provide a TAP-MAC mapping. In other words, requests coming
37
from unregistered TAP interfaces (without a binding file) are ignored, and
38
packet processing happens as if nfdhcpd didn't exist in the first place.
39
Requests coming from a registered device with but with different are considered
40
as snooping attempts and are dropped.
41

  
42
e) nfdhcpd is written in pure Python and uses scapy for packet
43
processing. This has proved super-useful when trying to troubleshooting
44
networking problems in production.
45

  
46
A simple scenario
47
-----------------
48

  
49
a) nfdhcpd starts. Upon initialization, it creates an NFQUEUE (e.g., 42,
50
configurable), and listens on it for incoming DHCP requests. It also begins to
51
watch its state directory, `/var/lib/nfdhcpd` via inotify().
52

  
53
b) A new VM gets created, let's assume its NIC has address mac0, lives on TAP
54
interface tap0, and is to receive IP address ip0 via DHCP.
55

  
56
c) Someone (e.g., a Ganeti KVM ifup script, or in our case snf-network [2]
57
creates a new binding file informing nfdhcpd that it is to reply to DHCP
58
requests from MAC mac0 on TAP interface tap0, and include IP ip0 in the DHCP
59
reply.
60

  
61
d) The ifup script or the administrator injects nfdhcpd in the processing
62
pipeline for packets coming from tap0, using iptables:
63

  
64
.. code-block:: console
65

  
66
  # iptables -t mangle -A PREROUTING -i tap0 -m udp -p udp --dport 67 -j NFQUEUE --queue-num 42
67

  
68
e) From now on, whenever a DHCP request is sent out by the VM, the
69
iptables rule will forward the packet to nfdhcpd, which will consult
70
its bindings database, find the entry for tap0, verify the source MAC,
71
and inject a DHCP reply for the corresponding IP address into tap0.
72

  
73
Binding file
74
------------
75

  
76
A binding file in nfdhcpd's state directory is named after the
77
physical interface where the daemon is to receive incoming DHCP requests
78
from, and defines at least the following variables:
79

  
80
* ``INSTANCE``: The instance name related to this inteface
81

  
82
* ``INDEV``: The logical interface where the packet is received on. For
83
  bridged setups, the bridge interface, e.g., br0. Otherwise, same as
84
  the file name.
85

  
86
* ``MAC``: The MAC address where the DHCP request must be originating from
87

  
88
* ``IP``: The IPv4 address to be returned in DHCP replies
89

  
90
* ``SUBNET``: The IPv4 subnet to be returned in DHCP replies in CIDR form
91

  
92
* ``GATEWAY``: The IPv4 gateway to be returned in DHCP replies
93

  
94
* ``SUBNET6``: The IPv6 network prefix
95

  
96
* ``GATEWAY6``: The IPv6 network gateway
97

  
98
* ``EUI64``: The IPv6 address of the instance
99

  
100

  
101
nfdhcpd.conf
102
------------
103

  
104
The configuration file for nfdhcp is `/etc/nfdhpcd/nfdhcpd.conf`. Three
105
sections are defined: general, dhcp, ipv6.
106

  
107
Note that nfdhcpd can run as nobody. This and other options related to
108
its execution environment are defined in general section.
109

  
110
In the dhcp section we define the options related to DHCP responses.
111
Specifically:
112

  
113
* ``enable_dhcp`` to globally enable/disable DHCP
114

  
115
* ``server_ip`` a dummy IP that the VMs will as src IP of the response
116

  
117
* ``dhcp_queue`` the a NFQUEUE number to listen on for DHCP requests
118

  
119
| Please not that this queue *must* be used in iptables mangle rule.
120

  
121
* ``nameservers`` IPv4 nameservers to include in DHCP responses
122

  
123
* ``domain`` the domain to serve with the replies (optional)
124

  
125
| If not given the instance's name (hostname) will be used instead.
126

  
127
In the ipv6 section we define the options related to IPv6 responses.  Currently
128
nfdhcpd supports IPv6 stateless configuration [3]. The instance will get an
129
auto-generated IPv6 (MAC to eui64) based on the IPv6 prefix exported by Router
130
Advertisements (O flag set, M flag unset). This kind of RA will make instance
131
query for nameservers and domain search list via DHCPv6 request.
132
nfdhcpd, currently and in case of IPv6, is supposed to work on a routed setup
133
where the instances are not on the same collision domain with the external
134
router and thus any RA/NA should be served locally. Specifically:
135

  
136
* ``enable_ipv6`` to globally enable/disable IPv6 responses
137

  
138
* ``ra_period`` to define how often nfdhcpd will send RAs to TAPs with IPv6
139

  
140
* ``rs_queue`` the NFQUEUE number to listen on for router solicitations
141

  
142
* ``ns_queue`` the NFQUEUE number to listen on for neighbor solicitations
143

  
144
* ``dhcp_queue`` the NFQUEUE number to listen on for DHCPv6 request
145

  
146
* ``nmeservers`` the IPv6 nameservers
147

  
148
| They can be send using the RDNSS option of the RA [4].
149
| Since it is not supported by Windows we serve them via DHCPv6 responses
150

  
151
* ``domains`` the domain search list
152

  
153
| If not given the instance's name (hostname) will be used instead.
154

  
155
iptables
156
--------
157

  
158
In order nfdhcpd to be able to process incoming requests you have to mangle
159
the corresponding packages. Please note that in case of bridged setup the
160
kernel understands that the packets are coming from the bridge (logical indev)
161
and not from the tap (physical indev). Specifically:
162

  
163
* **DHCP**: ``iptables -t mangle -A PREROUTING -i tap+ -p udp --dport 67 -j NFQUEUE --queue-num 42``
164

  
165
* **RS**: ``ip6tables -t mangle -A PREROUTING -i tap+ -p icmpv6 --icmpv6-type router-solicitation -j NFQUEUE --queue-num 43``
166

  
167
* **NS**: ``ip6tables -t mangle -A PREROUTING -i tap+ -p icmpv6 --icmpv6-type neighbour-solicitation -j NFQUEUE --queue-num 44``
168

  
169
* **DHCPv6**: ``ip6tables -t mangle -A PREROUTING -i tap+ -p udp --dport 547 -j NFQUEUE --queue-num 45``
170

  
171
For a bridged setup replace tap+ with br+ in case of DHCP. Using nfdhcpd
172
for IPv6 in a bridged setup does not make any sense. The above rules are
173
included in `/etc/ferm/nfdhcpd.ferm` .
174
In case you use ferm, this file should be included in `/etc/ferm/ferm.conf`.
175
Otherwise an `rc.local` script can be used to issue those rules upon boot.
176

  
177

  
178

  
179
| [1] https://www.wzdftpd.net/redmine/projects/nfqueue-bindings/wiki/
180
| [2] https://code.grnet.gr/projects/snf-network/
181
| [3] https://tools.ietf.org/html/rfc4862
182
| [4] https://tools.ietf.org/html/rfc5006
b/docs/make.bat
1
@ECHO OFF
2

  
3
REM Command file for Sphinx documentation
4

  
5
if "%SPHINXBUILD%" == "" (
6
	set SPHINXBUILD=sphinx-build
7
)
8
set BUILDDIR=_build
9
set ALLSPHINXOPTS=-d %BUILDDIR%/doctrees %SPHINXOPTS% .
10
set I18NSPHINXOPTS=%SPHINXOPTS% .
11
if NOT "%PAPER%" == "" (
12
	set ALLSPHINXOPTS=-D latex_paper_size=%PAPER% %ALLSPHINXOPTS%
13
	set I18NSPHINXOPTS=-D latex_paper_size=%PAPER% %I18NSPHINXOPTS%
14
)
15

  
16
if "%1" == "" goto help
17

  
18
if "%1" == "help" (
19
	:help
20
	echo.Please use `make ^<target^>` where ^<target^> is one of
21
	echo.  html       to make standalone HTML files
22
	echo.  dirhtml    to make HTML files named index.html in directories
23
	echo.  singlehtml to make a single large HTML file
24
	echo.  pickle     to make pickle files
25
	echo.  json       to make JSON files
26
	echo.  htmlhelp   to make HTML files and a HTML help project
27
	echo.  qthelp     to make HTML files and a qthelp project
28
	echo.  devhelp    to make HTML files and a Devhelp project
29
	echo.  epub       to make an epub
30
	echo.  latex      to make LaTeX files, you can set PAPER=a4 or PAPER=letter
31
	echo.  text       to make text files
32
	echo.  man        to make manual pages
33
	echo.  texinfo    to make Texinfo files
34
	echo.  gettext    to make PO message catalogs
35
	echo.  changes    to make an overview over all changed/added/deprecated items
36
	echo.  linkcheck  to check all external links for integrity
37
	echo.  doctest    to run all doctests embedded in the documentation if enabled
38
	goto end
39
)
40

  
41
if "%1" == "clean" (
42
	for /d %%i in (%BUILDDIR%\*) do rmdir /q /s %%i
43
	del /q /s %BUILDDIR%\*
44
	goto end
45
)
46

  
47
if "%1" == "html" (
48
	%SPHINXBUILD% -b html %ALLSPHINXOPTS% %BUILDDIR%/html
49
	if errorlevel 1 exit /b 1
50
	echo.
51
	echo.Build finished. The HTML pages are in %BUILDDIR%/html.
52
	goto end
53
)
54

  
55
if "%1" == "dirhtml" (
56
	%SPHINXBUILD% -b dirhtml %ALLSPHINXOPTS% %BUILDDIR%/dirhtml
57
	if errorlevel 1 exit /b 1
58
	echo.
59
	echo.Build finished. The HTML pages are in %BUILDDIR%/dirhtml.
60
	goto end
61
)
62

  
63
if "%1" == "singlehtml" (
64
	%SPHINXBUILD% -b singlehtml %ALLSPHINXOPTS% %BUILDDIR%/singlehtml
65
	if errorlevel 1 exit /b 1
66
	echo.
67
	echo.Build finished. The HTML pages are in %BUILDDIR%/singlehtml.
68
	goto end
69
)
70

  
71
if "%1" == "pickle" (
72
	%SPHINXBUILD% -b pickle %ALLSPHINXOPTS% %BUILDDIR%/pickle
73
	if errorlevel 1 exit /b 1
74
	echo.
75
	echo.Build finished; now you can process the pickle files.
76
	goto end
77
)
78

  
79
if "%1" == "json" (
80
	%SPHINXBUILD% -b json %ALLSPHINXOPTS% %BUILDDIR%/json
81
	if errorlevel 1 exit /b 1
82
	echo.
83
	echo.Build finished; now you can process the JSON files.
84
	goto end
85
)
86

  
87
if "%1" == "htmlhelp" (
88
	%SPHINXBUILD% -b htmlhelp %ALLSPHINXOPTS% %BUILDDIR%/htmlhelp
89
	if errorlevel 1 exit /b 1
90
	echo.
91
	echo.Build finished; now you can run HTML Help Workshop with the ^
92
.hhp project file in %BUILDDIR%/htmlhelp.
93
	goto end
94
)
95

  
96
if "%1" == "qthelp" (
97
	%SPHINXBUILD% -b qthelp %ALLSPHINXOPTS% %BUILDDIR%/qthelp
98
	if errorlevel 1 exit /b 1
99
	echo.
100
	echo.Build finished; now you can run "qcollectiongenerator" with the ^
101
.qhcp project file in %BUILDDIR%/qthelp, like this:
102
	echo.^> qcollectiongenerator %BUILDDIR%\qthelp\nfdhcpd.qhcp
103
	echo.To view the help file:
104
	echo.^> assistant -collectionFile %BUILDDIR%\qthelp\nfdhcpd.ghc
105
	goto end
106
)
107

  
108
if "%1" == "devhelp" (
109
	%SPHINXBUILD% -b devhelp %ALLSPHINXOPTS% %BUILDDIR%/devhelp
110
	if errorlevel 1 exit /b 1
111
	echo.
112
	echo.Build finished.
113
	goto end
114
)
115

  
116
if "%1" == "epub" (
117
	%SPHINXBUILD% -b epub %ALLSPHINXOPTS% %BUILDDIR%/epub
118
	if errorlevel 1 exit /b 1
119
	echo.
120
	echo.Build finished. The epub file is in %BUILDDIR%/epub.
121
	goto end
122
)
123

  
124
if "%1" == "latex" (
125
	%SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex
126
	if errorlevel 1 exit /b 1
127
	echo.
128
	echo.Build finished; the LaTeX files are in %BUILDDIR%/latex.
129
	goto end
130
)
131

  
132
if "%1" == "text" (
133
	%SPHINXBUILD% -b text %ALLSPHINXOPTS% %BUILDDIR%/text
134
	if errorlevel 1 exit /b 1
135
	echo.
136
	echo.Build finished. The text files are in %BUILDDIR%/text.
137
	goto end
138
)
139

  
140
if "%1" == "man" (
141
	%SPHINXBUILD% -b man %ALLSPHINXOPTS% %BUILDDIR%/man
142
	if errorlevel 1 exit /b 1
143
	echo.
144
	echo.Build finished. The manual pages are in %BUILDDIR%/man.
145
	goto end
146
)
147

  
148
if "%1" == "texinfo" (
149
	%SPHINXBUILD% -b texinfo %ALLSPHINXOPTS% %BUILDDIR%/texinfo
150
	if errorlevel 1 exit /b 1
151
	echo.
152
	echo.Build finished. The Texinfo files are in %BUILDDIR%/texinfo.
153
	goto end
154
)
155

  
156
if "%1" == "gettext" (
157
	%SPHINXBUILD% -b gettext %I18NSPHINXOPTS% %BUILDDIR%/locale
158
	if errorlevel 1 exit /b 1
159
	echo.
160
	echo.Build finished. The message catalogs are in %BUILDDIR%/locale.
161
	goto end
162
)
163

  
164
if "%1" == "changes" (
165
	%SPHINXBUILD% -b changes %ALLSPHINXOPTS% %BUILDDIR%/changes
166
	if errorlevel 1 exit /b 1
167
	echo.
168
	echo.The overview file is in %BUILDDIR%/changes.
169
	goto end
170
)
171

  
172
if "%1" == "linkcheck" (
173
	%SPHINXBUILD% -b linkcheck %ALLSPHINXOPTS% %BUILDDIR%/linkcheck
174
	if errorlevel 1 exit /b 1
175
	echo.
176
	echo.Link check complete; look for any errors in the above output ^
177
or in %BUILDDIR%/linkcheck/output.txt.
178
	goto end
179
)
180

  
181
if "%1" == "doctest" (
182
	%SPHINXBUILD% -b doctest %ALLSPHINXOPTS% %BUILDDIR%/doctest
183
	if errorlevel 1 exit /b 1
184
	echo.
185
	echo.Testing of doctests in the sources finished, look at the ^
186
results in %BUILDDIR%/doctest/output.txt.
187
	goto end
188
)
189

  
190
:end

Also available in: Unified diff