Revision 51ce199a
b/Makefile | ||
---|---|---|
2 | 2 |
flowspyver = $(shell git describe --abbrev=0 | egrep -o '([0-9]+\.){1,10}[0-9]+' | sed -e 's/\./_/g') |
3 | 3 |
name = $(shell basename $(shell pwd)) |
4 | 4 |
|
5 |
.PHONY: dist distclean |
|
5 |
# You can set these variables from the command line. |
|
6 |
SPHINXOPTS = |
|
7 |
SPHINXBUILD = sphinx-build |
|
8 |
PAPER = |
|
9 |
BUILDDIR = doc/build |
|
10 |
|
|
11 |
# Internal variables. |
|
12 |
PAPEROPT_a4 = -D latex_paper_size=a4 |
|
13 |
PAPEROPT_letter = -D latex_paper_size=letter |
|
14 |
ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) doc/source |
|
15 |
|
|
16 |
.PHONY: help dist distclean docclean html latex text |
|
17 |
|
|
18 |
help: |
|
19 |
@echo "Please use \`make <target>' where <target> is one of" |
|
20 |
@echo " html to make standalone HTML files" |
|
21 |
@echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter" |
|
22 |
@echo " text to make standalone txt files" |
|
6 | 23 |
|
7 | 24 |
dist: |
8 | 25 |
git archive --format tar --prefix $(name)-$(flowspyver)/ -o $(name)-$(flowspyver).tar $(flowspytag) |
9 | 26 |
gzip -f $(name)-$(flowspyver).tar |
27 |
|
|
10 | 28 |
distclean: |
11 | 29 |
@rm -f *tar.gz |
12 | 30 |
|
31 |
docclean: |
|
32 |
-rm -rf $(BUILDDIR)/* |
|
33 |
|
|
34 |
html: |
|
35 |
$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html |
|
36 |
@echo |
|
37 |
@echo "Build finished. The HTML pages are in $(BUILDDIR)/html." |
|
38 |
|
|
39 |
latex: |
|
40 |
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex |
|
41 |
@echo |
|
42 |
@echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex." |
|
43 |
@echo "Run \`make all-pdf' or \`make all-ps' in that directory to" \ |
|
44 |
"run these through (pdf)latex." |
|
45 |
|
|
46 |
text: |
|
47 |
$(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text |
|
48 |
@echo |
|
49 |
@echo "Done" |
|
50 |
|
b/README.txt | ||
---|---|---|
1 |
=========== |
|
2 |
1. Tool requirements |
|
3 |
Note: Depending on your setup each of the following |
|
4 |
may depend on other packages |
|
5 |
|
|
6 |
* python-django |
|
7 |
* python-django-extensions |
|
8 |
* python-mysqldb |
|
9 |
* mysql-client-5.1 |
|
10 |
* python-gevent |
|
11 |
* python-django-south |
|
12 |
* python-django-celery |
|
13 |
* python-yaml |
|
14 |
* python-paramiko (>= 1.7.7.1) |
|
15 |
* python-memcache |
|
16 |
* python-django-registration |
|
17 |
* ncclient (http://ncclient.grnet.gr/, http://github.com/leopoul/ncclient) |
|
18 |
* nxpy (https://code.grnet.gr/projects/nxpy) |
|
19 |
* python-lxml |
|
20 |
* python-ipaddr |
|
21 |
* python-django-tinymce |
|
22 |
* apache2 |
|
23 |
* apache2-mod-proxy |
|
24 |
* apache2-mod-rewrite |
|
25 |
* apache2-shibboleth : The server should be setup as a Shibboleth SP |
|
26 |
* The tool requires an event supporting web server. It is suggested to deploy gunicorn |
|
27 |
* If you wish to link your own db tables (peers, networks, etc) with the tool, prefer MySQL MyISAM db engine and use views. |
|
28 | 1 |
|
29 |
===========
|
|
30 |
2. Tool architecture
|
|
2 |
Firewall on Demand
|
|
3 |
******************
|
|
31 | 4 |
|
32 |
Firewall on Demand applies, via Netconf, flow rules to a network device. These rules are then propagated via e-bgp to peering routers. |
|
33 |
Each user is authenticated against shibboleth. Authorization is performed via a combination of a Shibboleth attribute and the peer network |
|
34 |
address range that the user originates from. |
|
35 |
Components roles: |
|
36 |
- web server (gunicorn): server the tool to localhost:port and allows for events |
|
37 |
- memcached: Caches devices information and aids in syncing |
|
38 |
- gunicorn/beanstalk: Job queue that applies firewall rules in a serial manner to avoid locks |
|
39 |
|
|
40 |
=========== |
|
41 |
3. Operational requirements |
|
42 | 5 |
|
43 |
* Shibboleth authentication |
|
44 |
- Shibboleth attributes: |
|
45 |
- eduPersonPrincipalName: Provides a string that uniquely identifies an administrator in the management application. |
|
46 |
- eduPersonEntitlement: A specific URN value must be provided to authorize an administrator: urn:mace:grnet.gr:fod:admin |
|
47 |
- mail: The e-mail address (one or more) of the administrator. It is used for notifications from the management application. It may also be used for further communication, with prior consent. |
|
48 |
- givenName (optional): The person's first name. |
|
49 |
- sn (optional): The person's last name. |
|
50 |
|
|
6 |
Description |
|
51 | 7 |
=========== |
52 |
4. Installation Procedure |
|
53 |
|
|
54 |
4.1 Pre-installation |
|
55 |
Configure and setup celeryd, memcached, beanstalkd, web server (gunicorn mode: django), apache |
|
56 |
Copy settings.py.dist to settings.py and urls.py.dist to urls.py. |
|
57 |
In settings.py set the following according to your configuration: |
|
58 |
* DATABASES (to point to your local database). You could use views instead of tables for models: peer, peercontacts, peernetworks. For this to work we suggest MySQL with MyISAM db engine |
|
59 |
* STATIC_URL (static media directory) |
|
60 |
* TEMPLATE_DIRS |
|
61 |
* CACHE_BACKEND |
|
62 |
* NETCONF_DEVICE (tested with Juniper EX4200 but any BGP enabled Juniper should work) |
|
63 |
* NETCONF_USER (enable ssh and netconf on device) |
|
64 |
* NETCONF_PASS |
|
65 |
* BROKER_HOST (beanstalk host) |
|
66 |
* BROKER_PORT (beanstalk port) |
|
67 |
* SERVER_EMAIL |
|
68 |
* EMAIL_SUBJECT_PREFIX |
|
69 |
* BROKER_URL (beanstalk url) |
|
70 |
* SHIB_AUTH_ENTITLEMENT (if you go for Shibboleth authentication) |
|
71 |
* NOTIFY_ADMIN_MAILS (bcc mail addresses) |
|
72 |
* PROTECTED_SUBNETS (subnets for which source or destination address will prevent rule creation and notify the NOTIFY_ADMIN_MAILS) |
|
73 |
* PRIMARY_WHOIS |
|
74 |
* ALTERNATE_WHOIS |
|
75 |
|
|
76 |
4.2 Branding |
|
77 |
|
|
78 |
4.2.1 Logos |
|
79 |
|
|
80 |
Inside the static folder you will find two empty png files: fod_logo.xcf (Gimp file) and shib_login.dist.png. |
|
81 |
Edit those two with your favourite image processing software and save them as fod_logo.png (under static/img/) and shib_login.png (under static/). Image sizes are optimized to operate without any |
|
82 |
other code changes. In case you want to incorporate images of different sizes you have to fine tune css and/or html as well. |
|
83 |
|
|
84 |
4.2.2 Footer |
|
85 |
|
|
86 |
Under the templates folder (templates), you can alter the footer.html file to include your own footer messages, badges, etc. |
|
87 |
|
|
88 |
4.2.3 Welcome Page |
|
89 |
|
|
90 |
Under the templates folder (templates), you can alter the welcome page - welcome.html with your own images, carousel, videos, etc. |
|
91 |
|
|
92 |
4.3 Configuration Examples |
|
93 |
|
|
94 |
* Gunicorn configuration |
|
95 |
/etc/gunicorn.d/project: |
|
96 |
CONFIG = { |
|
97 |
'mode': 'django', |
|
98 |
'working_dir': '/path/to/flowspy', |
|
99 |
#'python': '/usr/bin/python', |
|
100 |
'args': ( |
|
101 |
'--bind=localhost:port', |
|
102 |
'--workers=1', |
|
103 |
'--timeout=360', |
|
104 |
#'--keepalive=90', |
|
105 |
'--worker-class=egg:gunicorn#gevent', |
|
106 |
'--log-level=debug', |
|
107 |
'--log-file=/path/to/fod.log', |
|
108 |
'settings.py', |
|
109 |
), |
|
110 |
} |
|
111 |
|
|
112 |
* Apache operates as a gunicorn Proxy with WSGI and Shibboleth modules enabled. |
|
113 |
Depending on the setup the apache configuration may vary. |
|
114 |
|
|
115 |
|
|
116 |
* Celeryd example configuration: |
|
117 |
/etc/default/celeryd: |
|
118 |
# Name of nodes to start, here we have a single node |
|
119 |
CELERYD_NODES="w1" |
|
120 |
# or we could have three nodes: |
|
121 |
#CELERYD_NODES="w1 w2 w3" |
|
122 |
|
|
123 |
# Where to chdir at start. |
|
124 |
CELERYD_CHDIR="/path/to/flowspy/" |
|
125 |
# How to call "manage.py celeryd_multi" |
|
126 |
CELERYD_MULTI="$CELERYD_CHDIR/manage.py celeryd_multi" |
|
127 |
|
|
128 |
# How to call "manage.py celeryctl" |
|
129 |
CELERYCTL="$CELERYD_CHDIR/manage.py celeryctl" |
|
130 |
|
|
131 |
# Extra arguments to celeryd |
|
132 |
#CELERYD_OPTS="--time-limit=300 --concurrency=8" |
|
133 |
CELERYD_OPTS="-E -B" |
|
134 |
# Name of the celery config module. |
|
135 |
CELERY_CONFIG_MODULE="celeryconfig" |
|
136 |
|
|
137 |
# %n will be replaced with the nodename. |
|
138 |
CELERYD_LOG_FILE="$CELERYD_CHDIR/celery_var/log/celery/%n.log" |
|
139 |
CELERYD_PID_FILE="$CELERYD_CHDIR/celery_var/run/celery/%n.pid" |
|
140 |
|
|
141 |
# Workers should run as an unprivileged user. |
|
142 |
CELERYD_USER="user" |
|
143 |
CELERYD_GROUP="usergroup" |
|
144 |
|
|
145 |
# Name of the projects settings module. |
|
146 |
export DJANGO_SETTINGS_MODULE="settings" |
|
147 |
|
|
148 |
|
|
149 |
4.4 Installation |
|
150 |
|
|
151 |
* Run: |
|
152 |
./manage.py syncdb |
|
153 |
to create all the necessary tables in the database. Enable the admin account to insert initial data for peers and their contact info. |
|
154 |
* Then to allow for south migrations: |
|
155 |
./manage.py migration |
|
156 |
* Only if you wish to obtain info for your peers from a whois server: |
|
157 |
If you have properly set the primary and alternate whois servers you could go for: |
|
158 |
./manage.py fetch_networks |
|
159 |
to automatically fill network info. |
|
160 |
Alternatively you could fill those info manually via the admin interface. |
|
161 |
* Via the admin interface, modify as required the existing (example.com) Site instance |
|
162 |
* Modify flatpages to suit your needs |
|
163 |
* Once Apache proxying and shibboleth modules are properly setup, login to the tool. If shibboleth SP is properly setup you should see a user pending activation message and an activation email should arrive at the NOTIFY_ADMIN_MAILS accounts. |
|
164 |
|
|
165 |
|
|
166 |
** To share ideas and ask questions drop an email at: leopoul-at-noc(dot)grnet{dot}gr |
|
167 | 8 |
|
9 |
Firewall on Demand applies, via Netconf, flow rules to a network |
|
10 |
device. These rules are then propagated via e-bgp to peering routers. |
|
11 |
Each user is authenticated against shibboleth. Authorization is |
|
12 |
performed via a combination of a Shibboleth attribute and the peer |
|
13 |
network address range that the user originates from. FoD is meant to |
|
14 |
operate over this architecture: |
|
15 |
|
|
16 |
+-----------+ +------------+ +------------+ |
|
17 |
| FoD | NETCONF | flowspec | ebgp | router | |
|
18 |
| web app +----------> device +--------> | |
|
19 |
+-----------+ +------+-----+ +------------+ |
|
20 |
| ebgp |
|
21 |
| |
|
22 |
+------v-----+ |
|
23 |
| router | |
|
24 |
| | |
|
25 |
+------------+ |
|
26 |
|
|
27 |
NETCONF is chosen as the mgmt protocol to apply rules to a single |
|
28 |
flowspec capable device. Rules are then propagated via igbp to all |
|
29 |
flowspec capable routers. Of course FoD could apply rules directly |
|
30 |
(via NETCONF always) to a router and then ibgp would do the rest. In |
|
31 |
GRNET's case the flowspec capable device is an EX4200. |
|
32 |
|
|
33 |
Attention: Make sure your FoD server has ssh access to your flowspec device. |
|
34 |
|
|
35 |
|
|
36 |
Installation Considerations |
|
37 |
=========================== |
|
38 |
|
|
39 |
You can find the installation instructions for Ubuntu 12.04.3 (64) |
|
40 |
with Django 1.3.x in install.txt file. FoD depends on a bunch of |
|
41 |
packages. Installing in Debian Squeeze proved to be really tough as |
|
42 |
the majority of the required packages are not provided by any repos |
|
43 |
and need to be installed manually. This guide presents the |
|
44 |
installation procedures for Ubuntu 12.04.3 (64) with Django 1.3.x. |
|
45 |
Really soon, we will provide a guide for Debian Wheezy. However, users |
|
46 |
who wish to go for Wheezy, need to read the Django 1.4 changelist. One |
|
47 |
of the most significant changes in Django 1.4 is that the application |
|
48 |
dir layout has to be restructured. Also bear in mind that Django 1.4 |
|
49 |
introduces new aspects when it comes to application library |
|
50 |
inclussions. |
|
51 |
|
|
52 |
Soon we will post a branch of FoD tailored for Django 1.4. |
|
53 |
|
|
54 |
|
|
55 |
Contact |
|
56 |
======= |
|
57 |
|
|
58 |
You can find more about FoD or raise your issues at GRNET FoD |
|
59 |
repository: https://code.grnet.gr/fod. |
|
60 |
|
|
61 |
You can contactus directly at leopoul{at}noc[dot]grnet(.)gr |
b/doc/source/conf.py | ||
---|---|---|
1 |
# -*- coding: utf-8 -*- |
|
2 |
# |
|
3 |
# fod documentation build configuration file, created by |
|
4 |
# sphinx-quickstart on Wed Oct 16 17:20:20 2013. |
|
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.append(os.path.abspath('.')) |
|
20 |
|
|
21 |
# -- General configuration ----------------------------------------------------- |
|
22 |
|
|
23 |
# Add any Sphinx extension module names here, as strings. They can be extensions |
|
24 |
# coming with Sphinx (named 'sphinx.ext.*') or your custom ones. |
|
25 |
extensions = [] |
|
26 |
|
|
27 |
# Add any paths that contain templates here, relative to this directory. |
|
28 |
templates_path = ['_templates'] |
|
29 |
|
|
30 |
# The suffix of source filenames. |
|
31 |
source_suffix = '.rst' |
|
32 |
|
|
33 |
# The encoding of source files. |
|
34 |
#source_encoding = 'utf-8' |
|
35 |
|
|
36 |
# The master toctree document. |
|
37 |
master_doc = 'index' |
|
38 |
|
|
39 |
# General information about the project. |
|
40 |
project = u'fod' |
|
41 |
copyright = u'2013, Leonidas Poulopoulos' |
|
42 |
|
|
43 |
# The version info for the project you're documenting, acts as replacement for |
|
44 |
# |version| and |release|, also used in various other places throughout the |
|
45 |
# built documents. |
|
46 |
# |
|
47 |
# The short X.Y version. |
|
48 |
version = '0.9.9' |
|
49 |
# The full version, including alpha/beta/rc tags. |
|
50 |
release = '0.9.9' |
|
51 |
|
|
52 |
# The language for content autogenerated by Sphinx. Refer to documentation |
|
53 |
# for a list of supported languages. |
|
54 |
#language = None |
|
55 |
|
|
56 |
# There are two options for replacing |today|: either, you set today to some |
|
57 |
# non-false value, then it is used: |
|
58 |
#today = '' |
|
59 |
# Else, today_fmt is used as the format for a strftime call. |
|
60 |
#today_fmt = '%B %d, %Y' |
|
61 |
|
|
62 |
# List of documents that shouldn't be included in the build. |
|
63 |
#unused_docs = [] |
|
64 |
|
|
65 |
# List of directories, relative to source directory, that shouldn't be searched |
|
66 |
# for source files. |
|
67 |
exclude_trees = [] |
|
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. Major themes that come with |
|
93 |
# Sphinx are currently 'default' and 'sphinxdoc'. |
|
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_use_modindex = 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, an OpenSearch description file will be output, and all pages will |
|
153 |
# contain a <link> tag referring to it. The value of this option must be the |
|
154 |
# base URL from which the finished HTML is served. |
|
155 |
#html_use_opensearch = '' |
|
156 |
|
|
157 |
# If nonempty, this is the file name suffix for HTML files (e.g. ".xhtml"). |
|
158 |
#html_file_suffix = '' |
|
159 |
|
|
160 |
# Output file base name for HTML help builder. |
|
161 |
htmlhelp_basename = 'foddoc' |
|
162 |
|
|
163 |
|
|
164 |
# -- Options for LaTeX output -------------------------------------------------- |
|
165 |
|
|
166 |
# The paper size ('letter' or 'a4'). |
|
167 |
#latex_paper_size = 'letter' |
|
168 |
|
|
169 |
# The font size ('10pt', '11pt' or '12pt'). |
|
170 |
#latex_font_size = '10pt' |
|
171 |
|
|
172 |
# Grouping the document tree into LaTeX files. List of tuples |
|
173 |
# (source start file, target name, title, author, documentclass [howto/manual]). |
|
174 |
latex_documents = [ |
|
175 |
('index', 'fod.tex', u'fod Documentation', |
|
176 |
u'Leonidas Poulopoulos', 'manual'), |
|
177 |
] |
|
178 |
|
|
179 |
# The name of an image file (relative to this directory) to place at the top of |
|
180 |
# the title page. |
|
181 |
#latex_logo = None |
|
182 |
|
|
183 |
# For "manual" documents, if this is true, then toplevel headings are parts, |
|
184 |
# not chapters. |
|
185 |
#latex_use_parts = False |
|
186 |
|
|
187 |
# Additional stuff for the LaTeX preamble. |
|
188 |
#latex_preamble = '' |
|
189 |
|
|
190 |
# Documents to append as an appendix to all manuals. |
|
191 |
#latex_appendices = [] |
|
192 |
|
|
193 |
# If false, no module index is generated. |
|
194 |
#latex_use_modindex = True |
b/doc/source/index.rst | ||
---|---|---|
1 |
.. fod documentation master file, created by |
|
2 |
sphinx-quickstart on Wed Oct 16 17:20:20 2013. |
|
3 |
You can adapt this file completely to your liking, but it should at least |
|
4 |
contain the root `toctree` directive. |
|
5 |
|
|
6 |
****************** |
|
7 |
Firewall on Demand |
|
8 |
****************** |
|
9 |
|
|
10 |
Description |
|
11 |
=========== |
|
12 |
Firewall on Demand applies, via Netconf, flow rules to a network device. These rules are then propagated via e-bgp to peering routers. Each user is authenticated against shibboleth. Authorization is performed via a combination of a Shibboleth attribute and the peer network address range that the user originates from. |
|
13 |
FoD is meant to operate over this architecture:: |
|
14 |
|
|
15 |
+-----------+ +------------+ +------------+ |
|
16 |
| FoD | NETCONF | flowspec | ebgp | router | |
|
17 |
| web app +----------> device +--------> | |
|
18 |
+-----------+ +------+-----+ +------------+ |
|
19 |
| ebgp |
|
20 |
| |
|
21 |
+------v-----+ |
|
22 |
| router | |
|
23 |
| | |
|
24 |
+------------+ |
|
25 |
|
|
26 |
NETCONF is chosen as the mgmt protocol to apply rules to a single flowspec capable device. Rules are then propagated via igbp to all flowspec capable routers. Of course FoD could apply rules directly (via NETCONF always) to a router and then ibgp would do the rest. |
|
27 |
In GRNET's case the flowspec capable device is an EX4200. |
|
28 |
|
|
29 |
.. attention:: |
|
30 |
Make sure your FoD server has ssh access to your flowspec device. |
|
31 |
|
|
32 |
Installation Considerations |
|
33 |
=========================== |
|
34 |
You can find the installation instructions for Ubuntu 12.04.3 (64) with Django 1.3.x here: :doc:`Install FoD <install>`. |
|
35 |
FoD depends on a bunch of packages. Installing in Debian Squeeze proved to be really tough as the majority of the required packages are not provided by any repos and need to be installed manually. This guide presents the installation procedures for Ubuntu 12.04.3 (64) with Django 1.3.x. Really soon, we will provide a guide for Debian Wheezy. |
|
36 |
However, users who wish to go for Wheezy, need to read the Django 1.4 changelist. One of the most significant changes in Django 1.4 is that the application dir layout has to be restructured. |
|
37 |
Also bear in mind that Django 1.4 introduces new aspects when it comes to application library inclussions. |
|
38 |
|
|
39 |
Soon we will post a branch of FoD tailored for Django 1.4. |
|
40 |
|
|
41 |
Contact |
|
42 |
======= |
|
43 |
You can find more about FoD or raise your issues at `GRNET FoD repository <https://code.grnet.gr/projects/flowspy>`_. |
|
44 |
|
|
45 |
You can contact us directly at leopoul{at}noc[dot]grnet(.)gr |
|
46 |
|
|
47 |
Install |
|
48 |
======= |
|
49 |
|
|
50 |
.. toctree:: |
|
51 |
:maxdepth: 2 |
|
52 |
|
|
53 |
install |
|
54 |
|
|
55 |
|
b/doc/source/install.rst | ||
---|---|---|
1 |
************ |
|
2 |
Installation |
|
3 |
************ |
|
4 |
|
|
5 |
.. toctree:: |
|
6 |
:maxdepth: 2 |
|
7 |
|
|
8 |
Ubuntu 12.04.3 (64) - Django 1.3.x |
|
9 |
================================== |
|
10 |
|
|
11 |
This guide assumes that installation is carried out in /srv/flowspy directory. If other directory is to be used, please change the corresponding configuration files. It is also assumed that the root user will perform every action. |
|
12 |
|
|
13 |
Required system packages |
|
14 |
------------------------ |
|
15 |
|
|
16 |
Update and install the required packages:: |
|
17 |
|
|
18 |
apt-get update |
|
19 |
apt-get upgrade |
|
20 |
apt-get install mysql-server apache2 memcached libapache2-mod-proxy-html gunicorn beanstalkd python-django python-django-extensions python-django-south python-django-tinymce tinymce python-mysqldb python-yaml python-memcache python-django-registration python-ipaddr python-lxml mysql-client git python-django-celery python-paramiko python-gevent vim |
|
21 |
|
|
22 |
.. note:: |
|
23 |
Set username and password for mysql if used |
|
24 |
|
|
25 |
.. note:: |
|
26 |
If you wish to deploy an outgoing mail server, now it is time to do it. Otherwise you could set FoD to send out mails via a third party account |
|
27 |
|
|
28 |
Required application packages |
|
29 |
----------------------------- |
|
30 |
Get the required packages and install them |
|
31 |
|
|
32 |
- ncclient: NETCONF python client:: |
|
33 |
|
|
34 |
cd ~ |
|
35 |
git clone https://github.com/leopoul/ncclient.git |
|
36 |
cd ncclient |
|
37 |
python setup.py install |
|
38 |
|
|
39 |
- nxpy: Python Objects from/to XML proxy:: |
|
40 |
|
|
41 |
cd ~ |
|
42 |
git clone https://code.grnet.gr/git/nxpy |
|
43 |
cd nxpy |
|
44 |
python setup.py install |
|
45 |
|
|
46 |
- flowspy: core application. Installation is done at /srv/flowspy:: |
|
47 |
|
|
48 |
cd /srv |
|
49 |
git clone https://code.grnet.gr/git/flowspy |
|
50 |
cd flowspy |
|
51 |
|
|
52 |
Application configuration |
|
53 |
========================= |
|
54 |
|
|
55 |
Copy settings.py.dist to settings.py:: |
|
56 |
|
|
57 |
cp settings.py.dist settings.py |
|
58 |
|
|
59 |
Edit settings.py file and set the following according to your configuration:: |
|
60 |
|
|
61 |
ADMINS: set your admin name and email (assuming that your server can send notifications) |
|
62 |
DATABASES (to point to your local database). You could use views instead of tables for models: peer, peercontacts, peernetworks. For this to work we suggest MySQL with MyISAM db engine |
|
63 |
SECRET_KEY : Make this unique, and don't share it with anybody |
|
64 |
STATIC_URL (static media directory) . If you have followed the above this should be: /srv/flowspy/static |
|
65 |
TEMPLATE_DIRS : If you have followed the above this should be: /srv/flowspy/templates |
|
66 |
CACHE_BACKEND: If you have followed the above this should be: memcached://127.0.0.1:11211/?timeout=3600 |
|
67 |
Alternatively you could go for redis with the corresponding Django client lib. |
|
68 |
NETCONF_DEVICE (tested with Juniper EX4200 but any BGP enabled Juniper should work). This is the flowspec capable device |
|
69 |
NETCONF_USER (enable ssh and netconf on device) |
|
70 |
NETCONF_PASS |
|
71 |
If beanstalk is selected the following should be left intact. |
|
72 |
BROKER_HOST (beanstalk host) |
|
73 |
BROKER_PORT (beanstalk port) |
|
74 |
SERVER_EMAIL |
|
75 |
EMAIL_SUBJECT_PREFIX |
|
76 |
If beanstalk is selected the following should be left intact. |
|
77 |
BROKER_URL (beanstalk url) |
|
78 |
SHIB_AUTH_ENTITLEMENT (if you go for Shibboleth authentication) |
|
79 |
NOTIFY_ADMIN_MAILS (bcc mail addresses) |
|
80 |
PROTECTED_SUBNETS (subnets for which source or destination address will prevent rule creation and notify the NOTIFY_ADMIN_MAILS) |
|
81 |
The whois client is meant to be used in case you have inserted peers with their ASes in the peers table and wish to get network info for each one in an automated manner. |
|
82 |
PRIMARY_WHOIS |
|
83 |
ALTERNATE_WHOIS |
|
84 |
If you wish to deploy FoD with Shibboleth change the following attributes according to your setup: |
|
85 |
SHIB_AUTH_ENTITLEMENT = 'urn:mace' |
|
86 |
SHIB_ADMIN_DOMAIN = 'example.com' |
|
87 |
SHIB_LOGOUT_URL = 'https://example.com/Shibboleth.sso/Logout' |
|
88 |
SHIB_USERNAME = ['HTTP_EPPN'] |
|
89 |
SHIB_MAIL = ['mail', 'HTTP_MAIL', 'HTTP_SHIB_INETORGPERSON_MAIL'] |
|
90 |
SHIB_FIRSTNAME = ['HTTP_SHIB_INETORGPERSON_GIVENNAME'] |
|
91 |
SHIB_LASTNAME = ['HTTP_SHIB_PERSON_SURNAME'] |
|
92 |
SHIB_ENTITLEMENT = ['HTTP_SHIB_EP_ENTITLEMENT'] |
|
93 |
|
|
94 |
If you have not installed an outgoing mail server you can always use your own account (either corporate or gmail, hotmail ,etc) by adding the following lines in settings.py:: |
|
95 |
|
|
96 |
EMAIL_USE_TLS = True #(or False) |
|
97 |
EMAIL_HOST = 'smtp.example.com' |
|
98 |
EMAIL_HOST_USER = 'username' |
|
99 |
EMAIL_HOST_PASSWORD = 'yourpassword' |
|
100 |
EMAIL_PORT = 587 #(outgoing) |
|
101 |
|
|
102 |
|
|
103 |
.. note:: |
|
104 |
Soon we will release a version with django-registration as a means to add users and Shibboleth as an alternative |
|
105 |
|
|
106 |
Let's move on with some copies and dir creations:: |
|
107 |
|
|
108 |
cp urls.py.dist urls.py |
|
109 |
mkdir log |
|
110 |
chown -R root:www-data log/ |
|
111 |
chmod -R g+w log |
|
112 |
|
|
113 |
System configuration |
|
114 |
==================== |
|
115 |
Apache operates as a gunicorn Proxy with WSGI and Shibboleth modules enabled. |
|
116 |
Depending on the setup the apache configuration may vary:: |
|
117 |
|
|
118 |
a2enmod rewrite |
|
119 |
a2enmod proxy |
|
120 |
a2enmod ssl |
|
121 |
a2enmod proxy_http |
|
122 |
|
|
123 |
If shibboleth is to be used:: |
|
124 |
|
|
125 |
apt-get install libapache2-mod-shib2 |
|
126 |
a2enmod shib2 |
|
127 |
|
|
128 |
Now it is time to configure beanstalk, gunicorn, celery and apache. |
|
129 |
|
|
130 |
beanstalkd |
|
131 |
---------- |
|
132 |
|
|
133 |
Enable beanstalk by editting /etc/default/beanstalkd:: |
|
134 |
|
|
135 |
vim /etc/default/beanstalkd |
|
136 |
|
|
137 |
Uncomment the line **START=yes** to enable beanstalk |
|
138 |
|
|
139 |
Start beanstalkd:: |
|
140 |
|
|
141 |
service beanstalkd start |
|
142 |
|
|
143 |
gunicorn.d |
|
144 |
---------- |
|
145 |
|
|
146 |
create and edit /etc/gunicorn.d/fod:: |
|
147 |
|
|
148 |
vim /etc/gunicorn.d/fod |
|
149 |
|
|
150 |
FoD is served via gunicorn and is then proxied by Apache. If the above directory conventions have been followed so far, then your configuration should be:: |
|
151 |
|
|
152 |
CONFIG = { |
|
153 |
'mode': 'django', |
|
154 |
'working_dir': '/srv/flowspy', |
|
155 |
'args': ( |
|
156 |
'--bind=127.0.0.1:8081', |
|
157 |
'--workers=1', |
|
158 |
'--timeout=360', |
|
159 |
'--worker-class=egg:gunicorn#gevent', |
|
160 |
'--log-level=debug', |
|
161 |
'settings.py', |
|
162 |
), |
|
163 |
} |
|
164 |
|
|
165 |
celery.d |
|
166 |
-------- |
|
167 |
|
|
168 |
Celery is used over beanstalkd to apply firewall rules in a serial manner so that locks are avoided on the flowspec capable device. In our setup celery runs via django. That is why the python-django-celery package was installed. |
|
169 |
|
|
170 |
.. note:: |
|
171 |
Make sure that /etc/init.d/celeryd exists. |
|
172 |
|
|
173 |
celeryd requires a /etc/default/celeryd file to be in place. |
|
174 |
Thus we are going to create this file (/etc/default/celeryd):: |
|
175 |
|
|
176 |
vim /etc/default/celeryd |
|
177 |
|
|
178 |
Again if the directory conventions have been followed the file should be:: |
|
179 |
|
|
180 |
# Name of nodes to start, here we have a single node |
|
181 |
CELERYD_NODES="w1" |
|
182 |
# or we could have three nodes: |
|
183 |
#CELERYD_NODES="w1 w2 w3" |
|
184 |
|
|
185 |
# Where to chdir at start. |
|
186 |
CELERYD_CHDIR="/srv/flowspy/" |
|
187 |
# How to call "manage.py celeryd_multi" |
|
188 |
CELERYD_MULTI="$CELERYD_CHDIR/manage.py celeryd_multi" |
|
189 |
|
|
190 |
# How to call "manage.py celeryctl" |
|
191 |
CELERYCTL="$CELERYD_CHDIR/manage.py celeryctl" |
|
192 |
|
|
193 |
# Extra arguments to celeryd |
|
194 |
#CELERYD_OPTS="--time-limit=300 --concurrency=8" |
|
195 |
CELERYD_OPTS="-E -B" |
|
196 |
# Name of the celery config module. |
|
197 |
CELERY_CONFIG_MODULE="celeryconfig" |
|
198 |
|
|
199 |
# %n will be replaced with the nodename. |
|
200 |
CELERYD_LOG_FILE="$CELERYD_CHDIR/celery_var/log/celery/%n.log" |
|
201 |
CELERYD_PID_FILE="$CELERYD_CHDIR/celery_var/run/celery/%n.pid" |
|
202 |
|
|
203 |
# Workers should run as an unprivileged user. |
|
204 |
CELERYD_USER="root" |
|
205 |
CELERYD_GROUP="root" |
|
206 |
|
|
207 |
# Name of the projects settings module. |
|
208 |
export DJANGO_SETTINGS_MODULE="settings" |
|
209 |
|
|
210 |
Apache |
|
211 |
------ |
|
212 |
Apache proxies gunicorn. Things are more flexible here as you may follow your own configuration and conventions. Create and edit /etc/apache2/sites-available/fod. You should set <server_name> and <admin_mail> along with your certificates. If under testing environment, you can use the provided snakeoil certs. If you do not intent to use Shibboleth delete or comment the corresponding configuration parts inside **Shibboleth configuration** :: |
|
213 |
|
|
214 |
vim /etc/apache2/sites-available/fod |
|
215 |
|
|
216 |
Again if the directory conventions have been followed the file should be:: |
|
217 |
|
|
218 |
<VirtualHost *:80> |
|
219 |
ServerAdmin webmaster@localhost |
|
220 |
ServerName <server_name> |
|
221 |
DocumentRoot /var/www |
|
222 |
<Directory /> |
|
223 |
Options FollowSymLinks |
|
224 |
AllowOverride None |
|
225 |
</Directory> |
|
226 |
<Directory /var/www/> |
|
227 |
Options Indexes FollowSymLinks MultiViews |
|
228 |
AllowOverride None |
|
229 |
Order allow,deny |
|
230 |
allow from all |
|
231 |
</Directory> |
|
232 |
|
|
233 |
ScriptAlias /cgi-bin/ /usr/lib/cgi-bin/ |
|
234 |
<Directory "/usr/lib/cgi-bin"> |
|
235 |
AllowOverride None |
|
236 |
Options +ExecCGI -MultiViews +SymLinksIfOwnerMatch |
|
237 |
Order allow,deny |
|
238 |
Allow from all |
|
239 |
</Directory> |
|
240 |
|
|
241 |
ErrorLog ${APACHE_LOG_DIR}/error.log |
|
242 |
|
|
243 |
# Possible values include: debug, info, notice, warn, error, crit, |
|
244 |
# alert, emerg. |
|
245 |
LogLevel warn |
|
246 |
|
|
247 |
CustomLog ${APACHE_LOG_DIR}/access.log combined |
|
248 |
|
|
249 |
Alias /doc/ "/usr/share/doc/" |
|
250 |
<Directory "/usr/share/doc/"> |
|
251 |
Options Indexes MultiViews FollowSymLinks |
|
252 |
AllowOverride None |
|
253 |
Order deny,allow |
|
254 |
Deny from all |
|
255 |
Allow from 127.0.0.0/255.0.0.0 ::1/128 |
|
256 |
</Directory> |
|
257 |
|
|
258 |
RewriteEngine On |
|
259 |
RewriteCond %{HTTPS} off |
|
260 |
RewriteRule ^/(.*) https://<server_name>/$1 [L,R] |
|
261 |
|
|
262 |
</VirtualHost> |
|
263 |
<VirtualHost *:443> |
|
264 |
ServerName <server_name> |
|
265 |
ServerAdmin <admin_mail> |
|
266 |
ServerSignature On |
|
267 |
|
|
268 |
SSLEngine on |
|
269 |
SSLCertificateFile /etc/ssl/certs/example.com.crt |
|
270 |
SSLCertificateChainFile /etc/ssl/certs/example.com.crt |
|
271 |
SSLCertificateKeyFile /etc/ssl/private/example.com.key |
|
272 |
|
|
273 |
AddDefaultCharset UTF-8 |
|
274 |
IndexOptions +Charset=UTF-8 |
|
275 |
|
|
276 |
# Shibboleth configuration |
|
277 |
ShibConfig /etc/shibboleth/shibboleth2.xml |
|
278 |
Alias /shibboleth-sp /usr/share/shibboleth |
|
279 |
|
|
280 |
<Location /fod/login> |
|
281 |
AuthType shibboleth |
|
282 |
ShibRequireSession On |
|
283 |
ShibUseHeaders On |
|
284 |
require valid-user |
|
285 |
</Location> |
|
286 |
|
|
287 |
# Shibboleth debugging CGI script |
|
288 |
ScriptAlias /shibboleth/test /usr/lib/cgi-bin/shibtest.cgi |
|
289 |
<Location /shibboleth/test> |
|
290 |
AuthType shibboleth |
|
291 |
ShibRequireSession On |
|
292 |
ShibUseHeaders On |
|
293 |
require valid-user |
|
294 |
</Location> |
|
295 |
|
|
296 |
<Location /Shibboleth.sso> |
|
297 |
SetHandler shib |
|
298 |
</Location> |
|
299 |
|
|
300 |
# End of Shibboleth configuration |
|
301 |
|
|
302 |
<Location /admin/media/> |
|
303 |
SetHandler None |
|
304 |
</Location> |
|
305 |
|
|
306 |
Alias /admin/media /usr/share/pyshared/django/contrib/admin/media |
|
307 |
Alias /media /usr/share/pyshared/django/contrib/admin/media |
|
308 |
DocumentRoot /var/www |
|
309 |
<Directory /var/www/> |
|
310 |
Options Indexes FollowSymLinks MultiViews |
|
311 |
AllowOverride None |
|
312 |
Order allow,deny |
|
313 |
allow from all |
|
314 |
</Directory> |
|
315 |
|
|
316 |
|
|
317 |
|
|
318 |
<Proxy *> |
|
319 |
Order allow,deny |
|
320 |
Allow from all |
|
321 |
</Proxy> |
|
322 |
|
|
323 |
SSLProxyEngine off |
|
324 |
ProxyErrorOverride off |
|
325 |
ProxyTimeout 28800 |
|
326 |
ProxyPass /fod http://localhost:8081/fod retry=0 |
|
327 |
ProxyPassReverse /fod http://localhost:8081/fod |
|
328 |
|
|
329 |
LogLevel warn |
|
330 |
ErrorLog /var/log/apache2/ssl-error.log |
|
331 |
CustomLog /var/log/apache2/ssl-access.log combined |
|
332 |
|
|
333 |
|
|
334 |
|
|
335 |
|
|
336 |
Alias /fodstatic /srv/flowspy/static |
|
337 |
|
|
338 |
</VirtualHost> |
|
339 |
|
|
340 |
You are not far away from deploying FoD. When asked for a super user, create one:: |
|
341 |
|
|
342 |
cd /srv/flowspy |
|
343 |
python manage.py syncdb |
|
344 |
python manage.py migrate |
|
345 |
|
|
346 |
Restart, gunicorn and apache:: |
|
347 |
|
|
348 |
service gunicorn restart && service apache2 restart |
|
349 |
|
|
350 |
Testing the platform |
|
351 |
==================== |
|
352 |
Log in to the admin interface via https://<your ip>/fod/admin. Go to Peer ranges and add a new range (part of/or a complete subnet), eg. 83.212.0.0/19 |
|
353 |
Go to Peers and add a new peer, eg. id: 1, name: Test, AS: 16503, tag: TEST and move the network you have crteated from Avalable to Chosen. From the admin front, go to User, and edit your user. From the bottom of the page, select the TEST peer and save. |
|
354 |
Last but not least, modify as required the existing (example.com) Site instance. You are done. As you are logged-n via the admin, there is no need for Shibboleth. Go to https://<your ip>/fod/ and create a new rule. Your rule should be applied on the flowspec capable device after aprox. 10 seconds. |
|
355 |
|
|
356 |
Branding |
|
357 |
======== |
|
358 |
Via the admin interface you can modify flatpages to suit your needs |
|
359 |
|
|
360 |
Logos |
|
361 |
----- |
|
362 |
Inside the static folder you will find two empty png files: fod_logo.xcf (Gimp file) and shib_login.dist.png. Edit those two with your favourite image processing software and save them as fod_logo.png (under static/img/) and shib_login.png (under static/). Image sizes are optimized to operate without any other code changes. In case you want to incorporate images of different sizes you have to fine tune css and/or html as well. |
|
363 |
|
|
364 |
Footer |
|
365 |
------ |
|
366 |
Under the templates folder (templates), you can alter the footer.html file to include your own footer messages, badges, etc. |
|
367 |
|
|
368 |
Welcome Page |
|
369 |
------------ |
|
370 |
Under the templates folder (templates), you can alter the welcome page - welcome.html with your own images, carousel, videos, etc. |
b/install.txt | ||
---|---|---|
1 |
|
|
2 |
Installation |
|
3 |
************ |
|
4 |
|
|
5 |
|
|
6 |
Ubuntu 12.04.3 (64) - Django 1.3.x |
|
7 |
================================== |
|
8 |
|
|
9 |
This guide assumes that installation is carried out in /srv/flowspy |
|
10 |
directory. If other directory is to be used, please change the |
|
11 |
corresponding configuration files. It is also assumed that the root |
|
12 |
user will perform every action. |
|
13 |
|
|
14 |
|
|
15 |
Required system packages |
|
16 |
------------------------ |
|
17 |
|
|
18 |
Update and install the required packages: |
|
19 |
|
|
20 |
apt-get update |
|
21 |
apt-get upgrade |
|
22 |
apt-get install mysql-server apache2 memcached libapache2-mod-proxy-html gunicorn beanstalkd python-django python-django-extensions python-django-south python-django-tinymce tinymce python-mysqldb python-yaml python-memcache python-django-registration python-ipaddr python-lxml mysql-client git python-django-celery python-paramiko python-gevent vim |
|
23 |
|
|
24 |
Note: Set username and password for mysql if used |
|
25 |
|
|
26 |
Note: If you wish to deploy an outgoing mail server, now it is time to do |
|
27 |
it. Otherwise you could set FoD to send out mails via a third party |
|
28 |
account |
|
29 |
|
|
30 |
|
|
31 |
Required application packages |
|
32 |
----------------------------- |
|
33 |
|
|
34 |
Get the required packages and install them |
|
35 |
|
|
36 |
* ncclient: NETCONF python client: |
|
37 |
|
|
38 |
cd ~ |
|
39 |
git clone https://github.com/leopoul/ncclient.git |
|
40 |
cd ncclient |
|
41 |
python setup.py install |
|
42 |
|
|
43 |
* nxpy: Python Objects from/to XML proxy: |
|
44 |
|
|
45 |
cd ~ |
|
46 |
git clone https://code.grnet.gr/git/nxpy |
|
47 |
cd nxpy |
|
48 |
python setup.py install |
|
49 |
|
|
50 |
* flowspy: core application. Installation is done at /srv/flowspy: |
|
51 |
|
|
52 |
cd /srv |
|
53 |
git clone https://code.grnet.gr/git/flowspy |
|
54 |
cd flowspy |
|
55 |
|
|
56 |
|
|
57 |
Application configuration |
|
58 |
========================= |
|
59 |
|
|
60 |
Copy settings.py.dist to settings.py: |
|
61 |
|
|
62 |
cp settings.py.dist settings.py |
|
63 |
|
|
64 |
Edit settings.py file and set the following according to your |
|
65 |
configuration: |
|
66 |
|
|
67 |
ADMINS: set your admin name and email (assuming that your server can send notifications) |
|
68 |
DATABASES (to point to your local database). You could use views instead of tables for models: peer, peercontacts, peernetworks. For this to work we suggest MySQL with MyISAM db engine |
|
69 |
SECRET_KEY : Make this unique, and don't share it with anybody |
|
70 |
STATIC_URL (static media directory) . If you have followed the above this should be: /srv/flowspy/static |
|
71 |
TEMPLATE_DIRS : If you have followed the above this should be: /srv/flowspy/templates |
|
72 |
CACHE_BACKEND: If you have followed the above this should be: memcached://127.0.0.1:11211/?timeout=3600 |
|
73 |
Alternatively you could go for redis with the corresponding Django client lib. |
|
74 |
NETCONF_DEVICE (tested with Juniper EX4200 but any BGP enabled Juniper should work). This is the flowspec capable device |
|
75 |
NETCONF_USER (enable ssh and netconf on device) |
|
76 |
NETCONF_PASS |
|
77 |
If beanstalk is selected the following should be left intact. |
|
78 |
BROKER_HOST (beanstalk host) |
|
79 |
BROKER_PORT (beanstalk port) |
|
80 |
SERVER_EMAIL |
|
81 |
EMAIL_SUBJECT_PREFIX |
|
82 |
If beanstalk is selected the following should be left intact. |
|
83 |
BROKER_URL (beanstalk url) |
|
84 |
SHIB_AUTH_ENTITLEMENT (if you go for Shibboleth authentication) |
|
85 |
NOTIFY_ADMIN_MAILS (bcc mail addresses) |
|
86 |
PROTECTED_SUBNETS (subnets for which source or destination address will prevent rule creation and notify the NOTIFY_ADMIN_MAILS) |
|
87 |
The whois client is meant to be used in case you have inserted peers with their ASes in the peers table and wish to get network info for each one in an automated manner. |
|
88 |
PRIMARY_WHOIS |
|
89 |
ALTERNATE_WHOIS |
|
90 |
If you wish to deploy FoD with Shibboleth change the following attributes according to your setup: |
|
91 |
SHIB_AUTH_ENTITLEMENT = 'urn:mace' |
|
92 |
SHIB_ADMIN_DOMAIN = 'example.com' |
|
93 |
SHIB_LOGOUT_URL = 'https://example.com/Shibboleth.sso/Logout' |
|
94 |
SHIB_USERNAME = ['HTTP_EPPN'] |
|
95 |
SHIB_MAIL = ['mail', 'HTTP_MAIL', 'HTTP_SHIB_INETORGPERSON_MAIL'] |
|
96 |
SHIB_FIRSTNAME = ['HTTP_SHIB_INETORGPERSON_GIVENNAME'] |
|
97 |
SHIB_LASTNAME = ['HTTP_SHIB_PERSON_SURNAME'] |
|
98 |
SHIB_ENTITLEMENT = ['HTTP_SHIB_EP_ENTITLEMENT'] |
|
99 |
|
|
100 |
If you have not installed an outgoing mail server you can always use |
|
101 |
your own account (either corporate or gmail, hotmail ,etc) by adding |
|
102 |
the following lines in settings.py: |
|
103 |
|
|
104 |
EMAIL_USE_TLS = True #(or False) |
|
105 |
EMAIL_HOST = 'smtp.example.com' |
|
106 |
EMAIL_HOST_USER = 'username' |
|
107 |
EMAIL_HOST_PASSWORD = 'yourpassword' |
|
108 |
EMAIL_PORT = 587 #(outgoing) |
|
109 |
|
|
110 |
Note: Soon we will release a version with django-registration as a means |
|
111 |
to add users and Shibboleth as an alternative |
|
112 |
|
|
113 |
Let's move on with some copies and dir creations: |
|
114 |
|
|
115 |
cp urls.py.dist urls.py |
|
116 |
mkdir log |
|
117 |
chown -R root:www-data log/ |
|
118 |
chmod -R g+w log |
|
119 |
|
|
120 |
|
|
121 |
System configuration |
|
122 |
==================== |
|
123 |
|
|
124 |
Apache operates as a gunicorn Proxy with WSGI and Shibboleth modules |
|
125 |
enabled. Depending on the setup the apache configuration may vary: |
|
126 |
|
|
127 |
a2enmod rewrite |
|
128 |
a2enmod proxy |
|
129 |
a2enmod ssl |
|
130 |
a2enmod proxy_http |
|
131 |
|
|
132 |
If shibboleth is to be used: |
|
133 |
|
|
134 |
apt-get install libapache2-mod-shib2 |
|
135 |
a2enmod shib2 |
|
136 |
|
|
137 |
Now it is time to configure beanstalk, gunicorn, celery and apache. |
|
138 |
|
|
139 |
|
|
140 |
beanstalkd |
|
141 |
---------- |
|
142 |
|
|
143 |
Enable beanstalk by editting /etc/default/beanstalkd: |
|
144 |
|
|
145 |
vim /etc/default/beanstalkd |
|
146 |
|
|
147 |
Uncomment the line **START=yes** to enable beanstalk |
|
148 |
|
|
149 |
Start beanstalkd: |
|
150 |
|
|
151 |
service beanstalkd start |
|
152 |
|
|
153 |
|
|
154 |
gunicorn.d |
|
155 |
---------- |
|
156 |
|
|
157 |
create and edit /etc/gunicorn.d/fod: |
|
158 |
|
|
159 |
vim /etc/gunicorn.d/fod |
|
160 |
|
|
161 |
FoD is served via gunicorn and is then proxied by Apache. If the above |
|
162 |
directory conventions have been followed so far, then your |
|
163 |
configuration should be: |
|
164 |
|
|
165 |
CONFIG = { |
|
166 |
'mode': 'django', |
|
167 |
'working_dir': '/srv/flowspy', |
|
168 |
'args': ( |
|
169 |
'--bind=127.0.0.1:8081', |
|
170 |
'--workers=1', |
|
171 |
'--timeout=360', |
|
172 |
'--worker-class=egg:gunicorn#gevent', |
|
173 |
'--log-level=debug', |
|
174 |
'settings.py', |
|
175 |
), |
|
176 |
} |
|
177 |
|
|
178 |
|
|
179 |
celery.d |
|
180 |
-------- |
|
181 |
|
|
182 |
Celery is used over beanstalkd to apply firewall rules in a serial |
|
183 |
manner so that locks are avoided on the flowspec capable device. In |
|
184 |
our setup celery runs via django. That is why the python-django-celery |
|
185 |
package was installed. |
|
186 |
|
|
187 |
Note: Make sure that /etc/init.d/celeryd exists. |
|
188 |
|
|
189 |
celeryd requires a /etc/default/celeryd file to be in place. Thus we |
|
190 |
are going to create this file (/etc/default/celeryd): |
|
191 |
|
|
192 |
vim /etc/default/celeryd |
|
193 |
|
|
194 |
Again if the directory conventions have been followed the file should |
|
195 |
be: |
|
196 |
|
|
197 |
# Name of nodes to start, here we have a single node |
|
198 |
CELERYD_NODES="w1" |
|
199 |
# or we could have three nodes: |
|
200 |
#CELERYD_NODES="w1 w2 w3" |
|
201 |
|
|
202 |
# Where to chdir at start. |
|
203 |
CELERYD_CHDIR="/srv/flowspy/" |
|
204 |
# How to call "manage.py celeryd_multi" |
|
205 |
CELERYD_MULTI="$CELERYD_CHDIR/manage.py celeryd_multi" |
|
206 |
|
|
207 |
# How to call "manage.py celeryctl" |
|
208 |
CELERYCTL="$CELERYD_CHDIR/manage.py celeryctl" |
|
209 |
|
|
210 |
# Extra arguments to celeryd |
|
211 |
#CELERYD_OPTS="--time-limit=300 --concurrency=8" |
|
212 |
CELERYD_OPTS="-E -B" |
|
213 |
# Name of the celery config module. |
|
214 |
CELERY_CONFIG_MODULE="celeryconfig" |
|
215 |
|
|
216 |
# %n will be replaced with the nodename. |
|
217 |
CELERYD_LOG_FILE="$CELERYD_CHDIR/celery_var/log/celery/%n.log" |
|
218 |
CELERYD_PID_FILE="$CELERYD_CHDIR/celery_var/run/celery/%n.pid" |
|
219 |
|
|
220 |
# Workers should run as an unprivileged user. |
|
221 |
CELERYD_USER="root" |
|
222 |
CELERYD_GROUP="root" |
|
223 |
|
|
224 |
# Name of the projects settings module. |
|
225 |
export DJANGO_SETTINGS_MODULE="settings" |
|
226 |
|
|
227 |
|
|
228 |
Apache |
|
229 |
------ |
|
230 |
|
|
231 |
Apache proxies gunicorn. Things are more flexible here as you may |
|
232 |
follow your own configuration and conventions. Create and edit |
|
233 |
/etc/apache2/sites-available/fod. You should set <server_name> and |
|
234 |
<admin_mail> along with your certificates. If under testing |
|
235 |
environment, you can use the provided snakeoil certs. If you do not |
|
236 |
intent to use Shibboleth delete or comment the corresponding |
|
237 |
configuration parts inside **Shibboleth configuration** |
|
238 |
|
|
239 |
vim /etc/apache2/sites-available/fod |
|
240 |
|
|
241 |
Again if the directory conventions have been followed the file should |
|
242 |
be: |
|
243 |
|
|
244 |
<VirtualHost *:80> |
|
245 |
ServerAdmin webmaster@localhost |
|
246 |
ServerName <server_name> |
|
247 |
DocumentRoot /var/www |
|
248 |
<Directory /> |
|
249 |
Options FollowSymLinks |
|
250 |
AllowOverride None |
|
251 |
</Directory> |
|
252 |
<Directory /var/www/> |
|
253 |
Options Indexes FollowSymLinks MultiViews |
|
254 |
AllowOverride None |
|
255 |
Order allow,deny |
|
256 |
allow from all |
|
257 |
</Directory> |
|
258 |
|
|
259 |
ScriptAlias /cgi-bin/ /usr/lib/cgi-bin/ |
|
260 |
<Directory "/usr/lib/cgi-bin"> |
|
261 |
AllowOverride None |
|
262 |
Options +ExecCGI -MultiViews +SymLinksIfOwnerMatch |
|
263 |
Order allow,deny |
|
264 |
Allow from all |
|
265 |
</Directory> |
|
266 |
|
|
267 |
ErrorLog ${APACHE_LOG_DIR}/error.log |
|
268 |
|
|
269 |
# Possible values include: debug, info, notice, warn, error, crit, |
|
270 |
# alert, emerg. |
|
271 |
LogLevel warn |
|
272 |
|
|
273 |
CustomLog ${APACHE_LOG_DIR}/access.log combined |
|
274 |
|
|
275 |
Alias /doc/ "/usr/share/doc/" |
|
276 |
<Directory "/usr/share/doc/"> |
|
277 |
Options Indexes MultiViews FollowSymLinks |
|
278 |
AllowOverride None |
|
279 |
Order deny,allow |
|
280 |
Deny from all |
|
281 |
Allow from 127.0.0.0/255.0.0.0 ::1/128 |
|
282 |
</Directory> |
|
283 |
|
|
284 |
RewriteEngine On |
|
285 |
RewriteCond %{HTTPS} off |
|
286 |
RewriteRule ^/(.*) https://<server_name>/$1 [L,R] |
|
287 |
|
|
288 |
</VirtualHost> |
|
289 |
<VirtualHost *:443> |
|
290 |
ServerName <server_name> |
|
291 |
ServerAdmin <admin_mail> |
|
292 |
ServerSignature On |
|
293 |
|
|
294 |
SSLEngine on |
|
295 |
SSLCertificateFile /etc/ssl/certs/example.com.crt |
|
296 |
SSLCertificateChainFile /etc/ssl/certs/example.com.crt |
|
297 |
SSLCertificateKeyFile /etc/ssl/private/example.com.key |
|
298 |
|
|
299 |
AddDefaultCharset UTF-8 |
|
300 |
IndexOptions +Charset=UTF-8 |
|
301 |
|
|
302 |
# Shibboleth configuration |
|
303 |
ShibConfig /etc/shibboleth/shibboleth2.xml |
|
304 |
Alias /shibboleth-sp /usr/share/shibboleth |
|
305 |
|
|
306 |
<Location /fod/login> |
|
307 |
AuthType shibboleth |
|
308 |
ShibRequireSession On |
|
309 |
ShibUseHeaders On |
|
310 |
require valid-user |
|
311 |
</Location> |
|
312 |
|
|
313 |
# Shibboleth debugging CGI script |
|
314 |
ScriptAlias /shibboleth/test /usr/lib/cgi-bin/shibtest.cgi |
|
315 |
<Location /shibboleth/test> |
|
316 |
AuthType shibboleth |
|
317 |
ShibRequireSession On |
|
318 |
ShibUseHeaders On |
|
319 |
require valid-user |
|
320 |
</Location> |
|
321 |
|
|
322 |
<Location /Shibboleth.sso> |
|
323 |
SetHandler shib |
|
324 |
</Location> |
|
325 |
|
|
326 |
# End of Shibboleth configuration |
|
327 |
|
|
328 |
<Location /admin/media/> |
|
329 |
SetHandler None |
|
330 |
</Location> |
|
331 |
|
|
332 |
Alias /admin/media /usr/share/pyshared/django/contrib/admin/media |
|
333 |
Alias /media /usr/share/pyshared/django/contrib/admin/media |
|
334 |
DocumentRoot /var/www |
|
335 |
<Directory /var/www/> |
|
336 |
Options Indexes FollowSymLinks MultiViews |
|
337 |
AllowOverride None |
|
338 |
Order allow,deny |
|
339 |
allow from all |
|
340 |
</Directory> |
|
341 |
|
|
342 |
|
|
343 |
|
|
344 |
<Proxy *> |
|
345 |
Order allow,deny |
|
346 |
Allow from all |
|
347 |
</Proxy> |
|
348 |
|
|
349 |
SSLProxyEngine off |
|
350 |
ProxyErrorOverride off |
|
351 |
ProxyTimeout 28800 |
|
352 |
ProxyPass /fod http://localhost:8081/fod retry=0 |
|
353 |
ProxyPassReverse /fod http://localhost:8081/fod |
|
354 |
|
|
355 |
LogLevel warn |
|
356 |
ErrorLog /var/log/apache2/ssl-error.log |
|
357 |
CustomLog /var/log/apache2/ssl-access.log combined |
|
358 |
|
|
359 |
|
|
360 |
|
|
361 |
|
|
362 |
Alias /fodstatic /srv/flowspy/static |
|
363 |
|
|
364 |
</VirtualHost> |
|
365 |
|
|
366 |
You are not far away from deploying FoD. When asked for a super user, |
|
367 |
create one: |
|
368 |
|
|
369 |
cd /srv/flowspy |
|
370 |
python manage.py syncdb |
|
371 |
python manage.py migrate |
|
372 |
|
|
373 |
Restart, gunicorn and apache: |
|
374 |
|
|
375 |
service gunicorn restart && service apache2 restart |
|
376 |
|
|
377 |
|
|
378 |
Testing the platform |
|
379 |
==================== |
|
380 |
|
|
381 |
Log in to the admin interface via https://<your ip>/fod/admin. Go to |
|
382 |
Peer ranges and add a new range (part of/or a complete subnet), eg. |
|
383 |
83.212.0.0/19 Go to Peers and add a new peer, eg. id: 1, name: Test, |
|
384 |
AS: 16503, tag: TEST and move the network you have crteated from |
|
385 |
Avalable to Chosen. From the admin front, go to User, and edit your |
|
386 |
user. From the bottom of the page, select the TEST peer and save. Last |
|
387 |
but not least, modify as required the existing (example.com) Site |
|
388 |
instance. You are done. As you are logged-n via the admin, there is no |
|
389 |
need for Shibboleth. Go to https://<your ip>/fod/ and create a new |
|
390 |
rule. Your rule should be applied on the flowspec capable device after |
|
391 |
aprox. 10 seconds. |
|
392 |
|
|
393 |
|
|
394 |
Branding |
|
395 |
======== |
|
396 |
|
|
397 |
Via the admin interface you can modify flatpages to suit your needs |
|
398 |
|
|
399 |
|
|
400 |
Logos |
|
401 |
----- |
|
402 |
|
|
403 |
Inside the static folder you will find two empty png files: |
|
404 |
fod_logo.xcf (Gimp file) and shib_login.dist.png. Edit those two with |
|
405 |
your favourite image processing software and save them as fod_logo.png |
|
406 |
(under static/img/) and shib_login.png (under static/). Image sizes |
|
407 |
are optimized to operate without any other code changes. In case you |
|
408 |
want to incorporate images of different sizes you have to fine tune |
|
409 |
css and/or html as well. |
|
410 |
|
|
411 |
|
|
412 |
Footer |
|
413 |
------ |
|
414 |
|
|
415 |
Under the templates folder (templates), you can alter the footer.html |
|
416 |
file to include your own footer messages, badges, etc. |
|
417 |
|
|
418 |
|
|
419 |
Welcome Page |
|
420 |
------------ |
|
421 |
|
|
422 |
Under the templates folder (templates), you can alter the welcome page |
|
423 |
- welcome.html with your own images, carousel, videos, etc. |
Also available in: Unified diff