http://docs.maas.io/2.1/hacking.html
Hacking MAAS
Coding style
MAAS follows the Launchpad Python Style Guide, except where it gets Launchpad specic, and where it talks about method
naming. MAAS instead adopts PEP-8 naming in all cases, so method names should usually use the lowercase_with_underscores
form.
Prerequisites
You can grab MAASs code manually from Launchpad but Bazaar makes it easy to fetch the last version of the code. First of all,
install Bazaar:
$ sudo apt-get install bzr
Then go into the directory where you want the code to reside and run:
$ bzr branch lp:maas maas && cd maas
MAAS depends on Postgres 9.1, Apache 2, daemontools, pyinotify, and many other packages. To install everything thats needed
for running and developing MAAS, run:
$ make install-dependencies
Careful: this will apt-get install many packages on your system, via sudo. It may prompt you for your password.
This will install bind9. As a result you will have an extra daemon running. If you are a developer and dont intend to run BIND
locally, you can disable the daemon by inserting exit 1 at the top of /etc/default/bind9. The package still needs to be installed
for tests though.
Python development dependencies are pulled automatically from PyPI when buildout runs. (buildout will be automatically
congured to create a cache, in order to improve build times. See utilities/configure-buildout.)
Javascript development dependencies are pulled automatically from npm when make runs. (npm will be automatically congured to
use a cache, in order to improve build times.)
Optional
The PyCharm IDE is a useful tool when developing MAAS. The MAAS team does not endorse any particular IDE, but .idea project
les are included with MAAS, so PyCharm is an easy choice.
Running tests
To run the whole suite:
$ make test
To run tests at a lower level of granularity:
$ ./bin/test.region src/maasserver/tests/test_api.py
$ ./bin/test.region src/maasserver/tests/test_api.py:AnonymousEnlistmentAPITest
The test runner is nose, so you can pass in options like --with-coverage and --nocapture (short option: -s). The latter is essential
when using pdb so that stdout is not adulterated.
Note:
When running make test through ssh from a machine with locales that are not set up on the machine that runs the tests, some tests will fail with
a MismatchError and an unsupported locale setting message. Running locale-gen for the missing locales or changing your locales on your
workstation to ones present on the server will solve the issue.
1 de 7
14/01/17 17:09
http://docs.maas.io/2.1/hacking.html
Note:
By default a MAAS installation runs 4 regiond processes at the same time. This will change it to only run 1 process in the foreground. This should
only be used for debugging. Once nished the breakpoint should be removed and maas-regiond service should be started.
2 de 7
14/01/17 17:09
http://docs.maas.io/2.1/hacking.html
$ make sampledata
By default, the snippet maas_proxy includes a denition for an http proxy running on port 8000 on the same host as the MAAS
server. This means you can either install squid-deb-proxy:
$ sudo apt-get install squid-deb-proxy
or you can edit contrib/snippets_v2/generic to remove the proxy denition.
Set the iSCSI cong to include the MAAS congs:
$ sudo tee -a /etc/tgt/targets.conf < contrib/tgt.conf
The http_proxy variable is only needed if youre downloading through a proxy; sudo wouldnt pass it on to the script without the
assignment. Or if you dont have it set but do want to download through a proxy, pass your proxys URL:
http_proxy=http://proxy.example.com/
Run the development webserver and watch all the logs go by:
$ make run
Point your browser to http://localhost:5240/MAAS/
If youve populated your instance with the sample data, you can login as a simple user using the test account (username: test,
password: test) or the admin account (username: admin, password: test).
At this point you may also want to download PXE boot resources.
To shut down the database cluster and clean up all other generated les in your branch:
$ make distclean
This sends jobs to each cluster controller, asking each to download the boot resources they require. This may download dozens or
hundreds of megabytes, so it may take a while. To save bandwidth, set an HTTP proxy beforehand:
$ bin/maas dev maas set-config name=http_proxy value=http://...
3 de 7
14/01/17 17:09
http://docs.maas.io/2.1/hacking.html
Conguring DHCP
MAAS requires a properly congured DHCP server so it can boot machines using PXE. MAAS can work with its own instance of the
ISC DHCP server, if you install the maas-dhcp package:
$ sudo apt-get install maas-dhcp
If you choose to run your own ISC DHCP server, there is a bit more conguration to do. First, run this tool to generate a
conguration that will work with MAAS:
$ maas-rack generate-dhcp-config [options]
Run maas-rack generate-dhcp-config -h to see the options. You will need to provide various IP details such as the range of IP
addresses to assign to clients. You can use the generated output to congure your systems ISC DHCP server, by inserting the
conguration in the /var/lib/maas/dhcpd.conf le.
Also, edit /etc/default/isc-dhcp-server to set the INTERFACES variable to just the network interfaces that should be serviced by
this DHCP server.
Now restart dhcpd:
$ sudo service isc-dhcp-server restart
None of this work is needed if you let MAAS run its own DHCP server by installing maas-dhcp.
Development services
The development environment uses daemontools to manage the various services that are required. These are all dened in
subdirectories in services/.
There are familiar service-like commands:
4 de 7
14/01/17 17:09
$
$
$
$
make
make
make
make
http://docs.maas.io/2.1/hacking.html
start
status
restart
stop
The latter is a dependency of distclean so just running make distclean when youve nished with your branch is enough to stop
everything.
Individual services can be manipulated too:
$ make services/rackd/@start
The @<action> pattern works for any of the services.
Theres an additional special action, run:
$ make run
This starts all services up and tails their log les. When youre done, kill tail (e.g. Ctrl-c), and all the services will be stopped.
However, when used with individual services:
$ make services/regiond/@run
it does something even cooler. First it shuts down the service, then it restarts it in the foreground so you can see the logs in the
console. More importantly, it allows you to use pdb, for example.
A note of caution: some of the services have slightly dierent behaviour when run in the foreground:
regiond (the webapp service) will be run with its auto-reloading enabled.
Theres a convenience target for hacking regiond that starts everything up, but with regiond in the foreground:
$ make run+regiond
Apparently Django needs a lot of debugging ;)
Database information
MAAS uses Django to manage changes to the database schema.
Be sure to have a look at Djangos migration documentation before you make any change.
5 de 7
14/01/17 17:09
http://docs.maas.io/2.1/hacking.html
Note that if you want to add a new model class youll need to import it in src/<application>/models/__init__.py
Generate the migration script with:
$ ./bin/maas-region makemigrations --name description_of_the_change maasserver
This will generate a migration module named src/maasserver/migrations/builtin
/<auto_number>_description_of_the_change.py. Dont forget to add that le to the project with:
$ bzr add src/maasserver/migrations/builtin/<auto_number>_description_of_the_change.py
To apply that migration, run:
$ make syncdb
Note:
When the South migrations run they are actually being ran under Django 1.6 and South that is provided in the MAAS source code in a tarball.
Located at src/maasserver/migrations/south/django16_south.tar.gz this le is extracted into a temporary folder and imported by MAAS to run
the South migrations.
6 de 7
14/01/17 17:09
http://docs.maas.io/2.1/hacking.html
Documentation
Use reST with the convention for headings as used in the Python documentation.
Copyright 2012-2015, MAAS Developers. Ubuntu and Canonical are registered trademarks of Canonical Ltd.
Revision 5482 (2016-10-14 11:45:28 -0400). Documentation generation date: 2016-11-04 12:15:03 +0200.
7 de 7
14/01/17 17:09