Revision 126f8f4e

b/.gitignore
1
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/snf-network.qhcp"
81
	@echo "To view the help file:"
82
	@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/snf-network.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/snf-network"
90
	@echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/snf-network"
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
# snf-network 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 = ['sphinx.ext.autodoc', 'sphinx.ext.doctest', 'sphinx.ext.intersphinx', 'sphinx.ext.todo', 'sphinx.ext.coverage', 'sphinx.ext.pngmath', 'sphinx.ext.ifconfig', 'sphinx.ext.viewcode']
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'snf-network'
44
copyright = u'2010-2013, GRNET S.A. All rights reserved'
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.2'
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
           'collapsiblesidebar': 'true',
101
           'footerbgcolor':    '#55b577',
102
           'footertextcolor':  '#000000',
103
           'sidebarbgcolor':   '#ffffff',
104
           'sidebarbtncolor':  '#f2f2f2',
105
           'sidebartextcolor': '#000000',
106
           'sidebarlinkcolor': '#328e4a',
107
           'relbarbgcolor':    '#55b577',
108
           'relbartextcolor':  '#ffffff',
109
           'relbarlinkcolor':  '#ffffff',
110
           'bgcolor':          '#ffffff',
111
           'textcolor':        '#000000',
112
           'headbgcolor':      '#ffffff',
113
           'headtextcolor':    '#000000',
114
           'headlinkcolor':    '#c60f0f',
115
           'linkcolor':        '#328e4a',
116
           'visitedlinkcolor': '#63409b',
117
           'codebgcolor':      '#eeffcc',
118
           'codetextcolor':    '#333333'
119
}
120

  
121
# Add any paths that contain custom themes here, relative to this directory.
122
#html_theme_path = []
123

  
124
# The name for this set of Sphinx documents.  If None, it defaults to
125
# "<project> v<release> documentation".
126
#html_title = None
127

  
128
# A shorter title for the navigation bar.  Default is the same as html_title.
129
#html_short_title = None
130

  
131
# The name of an image file (relative to this directory) to place at the top
132
# of the sidebar.
133
#html_logo = None
134

  
135
# The name of an image file (within the static path) to use as favicon of the
136
# docs.  This file should be a Windows icon file (.ico) being 16x16 or 32x32
137
# pixels large.
138
#html_favicon = None
139

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

  
145
# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
146
# using the given strftime format.
147
#html_last_updated_fmt = '%b %d, %Y'
148

  
149
# If true, SmartyPants will be used to convert quotes and dashes to
150
# typographically correct entities.
151
#html_use_smartypants = True
152

  
153
# Custom sidebar templates, maps document names to template names.
154
#html_sidebars = {}
155

  
156
# Additional templates that should be rendered to pages, maps page names to
157
# template names.
158
#html_additional_pages = {}
159

  
160
# If false, no module index is generated.
161
#html_domain_indices = True
162

  
163
# If false, no index is generated.
164
#html_use_index = True
165

  
166
# If true, the index is split into individual pages for each letter.
167
#html_split_index = False
168

  
169
# If true, links to the reST sources are added to the pages.
170
#html_show_sourcelink = True
171

  
172
# If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
173
#html_show_sphinx = True
174

  
175
# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
176
#html_show_copyright = True
177

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

  
183
# This is the file name suffix for HTML files (e.g. ".xhtml").
184
#html_file_suffix = None
185

  
186
# Output file base name for HTML help builder.
187
htmlhelp_basename = 'snf-networkdoc'
188

  
189

  
190
# -- Options for LaTeX output --------------------------------------------------
191

  
192
latex_elements = {
193
# The paper size ('letterpaper' or 'a4paper').
194
#'papersize': 'letterpaper',
195

  
196
# The font size ('10pt', '11pt' or '12pt').
197
#'pointsize': '10pt',
198

  
199
# Additional stuff for the LaTeX preamble.
200
#'preamble': '',
201
}
202

  
203
# Grouping the document tree into LaTeX files. List of tuples
204
# (source start file, target name, title, author, documentclass [howto/manual]).
205
latex_documents = [
206
  ('index', 'snf-network.tex', u'snf-network Documentation',
207
   u'Synnefo Development', 'manual'),
208
]
209

  
210
# The name of an image file (relative to this directory) to place at the top of
211
# the title page.
212
#latex_logo = None
213

  
214
# For "manual" documents, if this is true, then toplevel headings are parts,
215
# not chapters.
216
#latex_use_parts = False
217

  
218
# If true, show page references after internal links.
219
#latex_show_pagerefs = False
220

  
221
# If true, show URL addresses after external links.
222
#latex_show_urls = False
223

  
224
# Documents to append as an appendix to all manuals.
225
#latex_appendices = []
226

  
227
# If false, no module index is generated.
228
#latex_domain_indices = True
229

  
230

  
231
# -- Options for manual page output --------------------------------------------
232

  
233
# One entry per manual page. List of tuples
234
# (source start file, name, description, authors, manual section).
235
man_pages = [
236
    ('index', 'snf-network', u'snf-network Documentation',
237
     [u'Synnefo Development'], 1)
238
]
239

  
240
# If true, show URL addresses after external links.
241
#man_show_urls = False
242

  
243

  
244
# -- Options for Texinfo output ------------------------------------------------
245

  
246
# Grouping the document tree into Texinfo files. List of tuples
247
# (source start file, target name, title, author,
248
#  dir menu entry, description, category)
249
texinfo_documents = [
250
  ('index', 'snf-network', u'snf-network Documentation',
251
   u'Synnefo Development', 'snf-network', 'One line description of project.',
252
   'Miscellaneous'),
253
]
254

  
255
# Documents to append as an appendix to all manuals.
256
#texinfo_appendices = []
257

  
258
# If false, no module index is generated.
259
#texinfo_domain_indices = True
260

  
261
# How to display URL addresses: 'footnote', 'no', or 'inline'.
262
#texinfo_show_urls = 'footnote'
263

  
264
# If true, do not generate a @detailmenu in the "Top" node's menu.
265
#texinfo_no_detailmenu = False
266

  
267

  
268
# Example configuration for intersphinx: refer to the Python standard library.
269
intersphinx_mapping = {'http://docs.python.org/': None}
b/docs/index.rst
1
.. snf-network documentation master file, created by
2
   sphinx-quickstart on Wed Feb 12 20:00:16 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 snf-network's documentation!
7
=======================================
8

  
9
snf-network is a set of scripts that handle the network configuration of
10
an instance inside a Ganeti cluster. It takes advantange of the
11
variables that Ganeti exports to their execution environment and issue
12
all the necessary commands to ensure network connectivity to the instance
13
based on the requested setup.
14

  
15
Environment
16
-----------
17

  
18
Ganeti supports `IP pool management
19
<http://docs.ganeti.org/ganeti/master/html/design-network.html>`_
20
so that end-user can put instances inside networks and get all information
21
related to the network in scripts. Specifically the following options are
22
exported:
23

  
24
* IP
25
* MAC
26
* MODE
27
* LINK
28

  
29
are per NIC specific, whereas:
30

  
31
* NETWORK_SUBNET
32
* NETWORK_GATEWAY
33
* NETWORK_MAC_PREFIX
34
* NETWORK_TAGS
35
* NETWORK_SUBNET6
36
* NETWORK_GATEWAY6
37

  
38
are inherited by the network in which a NIC resides (optional).
39

  
40
Scripts
41
-------
42

  
43
The scripts can be devided into two categories:
44

  
45
1. The scripts that are invoked explicitly by Ganeti upon NIC creation.
46

  
47
2. The scripts that are invoked by Ganeti Hooks Manager before or after an
48
   opcode execution.
49

  
50
The first group has the exact NIC info that is about to be configured where
51
the latter one has the info of the whole instance. The big difference is that
52
instance configuration (from the master perspective) might vary or be total
53
different from the one that is currently running. The reason is that some
54
modifications can take place without hotplug.
55

  
56

  
57
kvm-ifup-custom
58
^^^^^^^^^^^^^^^
59

  
60
Ganeti upon instance startup and NIC hotplug creates the TAP devices to
61
reflect to the instance's NICs. After that it invokes the Ganeti's `kvm-ifup`
62
script with the TAP name as first argument and an environment including
63
all NIC's and the corresponding network's info. This script searches for
64
a user provided one under `/etc/ganeti/kvm-ifup-custom` and executes it
65
instead.
66

  
67

  
68
kvm-ifdown-custom
69
^^^^^^^^^^^^^^^^^
70

  
71
In order to cleanup or modify the node's setup or the configuration of an
72
external component, Ganeti upon instance shutdown, successful instance
73
migration on source node and NIC hot-unplug invokes `kvm-ifdown` script
74
with the TAP name as first argument and a boolean second argument pointing
75
whether we want to do local cleanup only (in case of instance migration) or
76
totally unconfigure the interface along with e.g., any DNS entries (in case
77
of NIC hot-unplug). This script searches for a user provided one under
78
`/etc/ganeti/kvm-ifdown-custom` and executes it instead.
79

  
80

  
81
vif-custom
82
^^^^^^^^^^
83

  
84
Ganeti provides a hypervisor parameter that defines the script to be executed
85
per NIC upon instance startup: `vif-script`. Ganeti provides `vif-ganeti` as
86
example script which executes `/etc/xen/scripts/vif-custom` if found.
87

  
88

  
89
snf-network-hook
90
^^^^^^^^^^^^^^^^
91

  
92
This hook gets all static info related to an instance from evironment variables
93
and issues any commands needed. It was used to fix node's setup upon migration
94
when ifdown script was not supported but now it does nothing.
95

  
96

  
97
snf-network-dnshook
98
^^^^^^^^^^^^^^^^^^^
99

  
100
This hook updates an external `DDNS <https://wiki.debian.org/DDNS>`_ setup via
101
``nsupdate``. Since we add/remove entries during ifup/ifdown scripts, we use
102
this only during instance remove/shutdown/rename. It does not rely on exported
103
environment but it queries first the DNS server to obtain current entries and
104
then it invokes the neccessary commands to remove them (and the relevant
105
reverse ones too).
106

  
107

  
108
Supported Setups
109
----------------
110

  
111
Currently since NICs in Ganeti are not taggable objects, we use network's and
112
instance's tags to customize each NIC configuration. NIC inherits the network's
113
tags (if attached to any) and further customization can be achieved with
114
instance tags e.g. <tag prefix>:<nic uuid or name>:<tag>. In the following
115
subsections we will mention all supported tags and their reflected underline
116
setup.
117

  
118

  
119
ip-less-routed
120
^^^^^^^^^^^^^^
121

  
122
This setup has the following characteristics:
123

  
124
* An external gateway on the same collition domain with all nodes on some
125
  interface (e.g. eth1, eth0.200) is needed.
126
* Each node is a router for the hostes VMs
127
* The node itself does not have an IP inside the routed network
128
* The node does proxy ARP for IPv4 networks
129
* The node does proxy NDP for IPv6 networks while RA and NA are
130
* RS and NS are served locally by
131
  `nfdhcpd <http://www.synnefo.org/docs/nfdhcpd/latest/index.html>`_
132
  since the VMs are not on the same link with the router.
133

  
134
Lets analyze a simple PING from an instance to an external IP using this setup.
135
We assume the following:
136

  
137
* ``IP`` is the instance's IP
138
* ``GW_IP`` is the external router's IP
139
* ``NODE_IP`` is the node's IP
140
* ``ARP_IP`` is a dummy IP inside the network needed for proxy ARP
141

  
142
* ``MAC`` is the instance's MAC
143
* ``TAP_MAC`` is the tap's MAC
144
* ``DEV_MAC`` is the host's DEV MAC
145
* ``GW_MAC`` is the external router's MAC
146

  
147
* ``DEV`` is the node's device that the router is visible from
148
* ``TAP`` is the host interface connected with the instance's eth0
149

  
150
Since we suppose to be on the same link with the router, ARP takes place first:
151

  
152
1) The VM wants to know the GW_MAC. Since the traffic is routed we do proxy ARP.
153

  
154
 - ARP, Request who-has GW_IP tell IP
155
 - ARP, Reply GW_IP is-at TAP_MAC ``echo 1 > /proc/sys/net/conf/TAP/proxy_arp``
156
 - So `arp -na` insided the VM shows: ``(GW_IP) at TAP_MAC [ether] on eth0``
157

  
158
2) The host wants to know the GW_MAC. Since the node does **not** have an IP
159
   inside the network we use the dummy one specified above.
160

  
161
 - ARP, Request who-has GW_IP tell ARP_IP (Created by DEV)
162
   ``arptables -I OUTPUT -o DEV --opcode 1 -j mangle --mangle-ip-s ARP_IP``
163
 - ARP, Reply GW_IP is-at GW_MAC
164

  
165
3) The host wants to know MAC so that it can proxy it.
166

  
167
 - We simulate here that the VM sees **only** GW on the link.
168
 - ARP, Request who-has IP tell GW_IP (Created by TAP)
169
   ``arptables -I OUTPUT -o TAP --opcode 1 -j mangle --mangle-ip-s GW_IP``
170
 - So `arp -na` inside the host shows:
171
   ``(GW_IP) at GW_MAC [ether] on DEV, (IP) at MAC on TAP``
172

  
173
4) GW wants to know who does proxy for IP.
174

  
175
 - ARP, Request who-has IP tell GW_IP
176
 - ARP, Reply IP is-at DEV_MAC (Created by host's DEV)
177

  
178

  
179
With the above we have a working proxy ARP configuration. The rest is done
180
via simple L3 routing. Lets assume the following:
181

  
182
* ``TABLE`` is the extra routing table
183
* ``SUBNET`` is the IPv4 subnet where the VM's IP reside
184

  
185
1) Outgoing traffic:
186

  
187
 - Traffic coming out of TAP is routed via TABLE
188
   ``ip rule add dev TAP table TABLE``
189
 - TABLE states that default route is GW_IP via DEV
190
   ``ip route add default via GW_IP dev DEV``
191

  
192
2) Incoming traffic:
193

  
194
 - Packet arrives at router
195
 - Router knows from proxy ARP that the IP is at DEV_MAC.
196
 - Router sends ethernet packet with tgt DEV_MAC
197
 - Host receives the packet from DEV interface
198
 - Traffic coming out DEV is routed via TABLE
199
   ``ip rule add dev DEV table TABLE``
200
 - Traffic targeting IP is routed to TAP
201
   ``ip route add IP dev TAP``
202

  
203
3) Host to VM traffic:
204

  
205
 - Impossible if the VM resides in the host
206
 - Otherwise there is a route for it: ``ip route add SUBNET dev DEV``
207

  
208
The IPv6 setup is pretty similar but instead of proxy ARP we have proxy NDP
209
and RS and NS coming from TAP are served by nfdhpcd. RA contain network's
210
prefix and has M flag unset in order the VM to obtain its IP6 via SLAAC and
211
O flag set to obtain static info (nameservers, domain search list) via DHCPv6
212
(also served by nfdhcpd).
213

  
214
Again the VM sees on its link local only TAP which is supposed to be the
215
Router. The host does proxy for IP6 ``ip -6 neigh add EUI64 dev DEV``.
216

  
217
When an interface gets up inside a host we should invalidate all entries
218
related to its IP among other nodes and the router. For proxy ARP we do
219
``arpsend -U -c 1 -i IP DEV`` and for proxy NDP we do ``ndsend EUI64 DEV``
220

  
221

  
222
private-filtered
223
^^^^^^^^^^^^^^^^
224

  
225
In order to provide L2 isolation among several VMs we can use ebtables on a
226
**single** bridge. The infrastracture must provide a physical VLAN or separate
227
interaface shared among all nodes in the cluster. All virtual interfaces will
228
be bridged on a common bridge (e.g. ``prv0``) and filtering will be done via
229
ebtables and MAC prefix. The concept is that all interfaces on the same L2
230
should have the same MAC prefix. MAC prefix uniqueness is quaranteed by
231
synnefo and passed to Ganeti as a network option.
232

  
233
To ensure isolation we should allow traffic coming from tap to have specific
234
source MAC and at the same time allow traffic coming to tap to have a source
235
MAC in the same MAC prefix. Applying those rules only in FORWARD chain will not
236
guarantee isolation. The reason is because packets with target MAC a `mutlicast
237
address <http://en.wikipedia.org/wiki/Multicast_address>`_ go through INPUT and
238
OUTPUT chains. To sum up the following ebtables rules are applied:
239

  
240
.. code-block:: console
241

  
242
  # Create new chains
243
  ebtables -t filter -N FROMTAP5
244
  ebtables -t filter -N TOTAP5
245

  
246
  # Filter multicast traffic from VM
247
  ebtables -t filter -A INPUT -i tap5 -j FROMTAP5
248

  
249
  # Filter multicast traffic to VM
250
  ebtables -t filter -A OUTPUT -o tap5 -j TOTAP5
251

  
252
  # Filter traffic from VM
253
  ebtables -t filter -A FORWARD -i tap5 -j FROMTAP5
254
  # Filter traffic to VM
255
  ebtables -t filter -A FORWARD -o tap5 -j TOTAP5
256

  
257
  # Allow only specific src MAC for outgoing traffic
258
  ebtables -t filter -A FROMTAP5 -s ! aa:55:66:1a:ae:82 -j DROP
259
  # Allow only specific src MAC prefix for incoming traffic
260
  ebtables -t filter -A TOTAP5 -s ! aa:55:60:0:0:0/ff:ff:f0:0:0:0 -j DROP
261

  
262

  
263
dns
264
^^^
265

  
266
snf-network can update an external `DDNS <https://wiki.debian.org/DDNS>`_
267
server.  `ifup` and `ifdown` scripts, if `dns` network tag is found, will use
268
`nsupdate` and add/remove entries related to the interface that is being
269
managed.
270

  
271

  
272
Contents:
273

  
274
.. toctree::
275
   :maxdepth: 2
276

  
277

  
278

  
279
Indices and tables
280
==================
281

  
282
* :ref:`genindex`
283
* :ref:`modindex`
284
* :ref:`search`
285

  
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\snf-network.qhcp
103
	echo.To view the help file:
104
	echo.^> assistant -collectionFile %BUILDDIR%\qthelp\snf-network.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