Anda di halaman 1dari 7

Hacking MAAS MAAS dev documentation

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

Hacking MAAS MAAS dev documentation

http://docs.maas.io/2.1/hacking.html

Running JavaScript tests


The JavaScript tests are run using Karma. Chromium and PhantomJS are the default browser but any browser supported by Karma
can be used to run the tests.:
$ ./bin/test.js
If you want to run the JavaScript tests in debug mode so you can inspect the code inside of a running browser you can launch
Karma manually.:
$ ./bin/karma start src/maastesting/karma.conf.js --browsers Chrome --no-single-run

Production MAAS server debugging


When MAAS is installed from packaging it can help to enable debugging features to triage issues.

Log all API and UI exceptions


By default MAAS only logs HTTP 500 - INTERNAL_SERVER_ERROR into the regiond.log. To enable logging of all exceptions even
exceptions where MAAS will return the correct HTTP status code.:
$ sudo sed -i 's/DEBUG = False/DEBUG = True/g' /usr/share/maas/maas/settings.py
$ sudo service maas-regiond restart

Run regiond in foreground


It can help when debugging to run regiond a foreground process so you can interact with the regiond by placing a breakpoint in
the code. Once you have placed a breakpoint into the code you want to inspect you can start the regiond process in the
foreground.:
$ sudo service maas-regiond stop
$ sudo -u maas -H DJANGO_SETTINGS_MODULE=maas.settings PYTHONPATH=/usr/share/maas twistd3 --nodaemon
--pidfile= maas-regiond

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.

Run rackd in foreground


It can help when debugging to run rackd a foreground process so you can interact with the rackd by placing a breakpoint in the
code. Once you have placed a breakpoint into the code you want to inspect you can start the rackd process in the foreground.:
$ sudo service maas-rackd stop
$ sudo -u maas -H /usr/bin/authbind --deep /usr/bin/twistd3 --nodaemon --pidfile= maas-rackd

Development MAAS server setup


Access to the database is congured in src/maas/development.py.
The Makefile or the test suite sets up a development database cluster inside your branch. It lives in the db directory, which gets
created on demand. Youll want to shut it down before deleting a branch; see below.
First, set up the project. This fetches all the required dependencies and sets up some useful commands in bin/:
$ make
Create the database cluster and initialise the development database:
$ make syncdb
Optionally, populate your database with the sample data:

2 de 7

14/01/17 17:09

Hacking MAAS MAAS dev documentation

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

Downloading PXE boot resources


To use PXE booting, each cluster controller needs to download several les relating to PXE booting. This process is automated,
but it does not start by default.
First create a superuser and start all MAAS services:
$ bin/maas-region createadmin
$ make run
Substitute your own email. The command will prompt for a choice of password.
Next, get the superusers API key on the account preferences page in the web UI, and use it to log into MAAS at the
command-line:
$ bin/maas login dev http://localhost:5240/MAAS/
Start downloading PXE boot resources:
$

bin/maas dev node-groups import-boot-images

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://...

Running the built-in TFTP server


You will need to run the built-in TFTP server on the real TFTP port (69) if you want to boot some real hardware. By default, its set
to start up on port 5244 for testing purposes. Make these changes:
* Use ``bin/maas-rack`` to change the tftp-port setting to 69
* Install the ``authbind``package:

3 de 7

14/01/17 17:09

Hacking MAAS MAAS dev documentation

http://docs.maas.io/2.1/hacking.html

$ sudo apt-get install authbind


* Create a file ``/etc/authbind/byport/69`` that is *executable* by the
user running MAAS.
$ sudo touch /etc/authbind/byport/69
$ sudo chmod a+x /etc/authbind/byport/69
Now when starting up the MAAS development webserver, make run and make start will detect authbinds presence and use it
automatically.

Running the BIND daemon for real


Theres a BIND daemon that is started up as part of the development service but it runs on port 5246 by default. If you want to
make it run as a real DNS server on the box then edit services/dns/run and change the port declaration there so it says:
port=53
Then as for TFTP above, create an authbind authorisation:
$ sudo touch /etc/authbind/byport/53
$ sudo chmod a+x /etc/authbind/byport/53
and run as normal.

Running the cluster worker


The cluster also needs authbind as it needs to bind a socket on UDP port 68 for DHCP probing:
$ sudo touch /etc/authbind/byport/68
$ sudo chmod a+x /etc/authbind/byport/68
If you omit this, nothing else will break, but you will get an error in the cluster log because it cant bind to the port.

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

Hacking MAAS MAAS dev documentation

$
$
$
$

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 ;)

Adding new dependencies


Since MAAS is distributed mainly as an Ubuntu package, all runtime dependencies should be packaged, and we should develop
with the packaged version if possible. All dependencies, from a package or not, need to be added to setup.py and buildout.cfg,
and the version specied in versions.cfg (allowed-picked-version is disabled, hence buildout must be given precise version
information).
If it is a development-only dependency (i.e. only needed for the test suite, or for developers convenience), simply running
buildout like this will make the necessary updates to versions.cfg:
$ ./bin/buildout -v buildout:allow-picked-versions=true

Adding new source les


When creating a new source le, a Python module or test for example, always start with the appropriate template from the
templates directory.

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.

Changing the schema


Once youve made a model change (i.e. a change to a le in src/<application>/models/*.py) you have to run Djangos
makemigrations command to create a migration le that will be stored in src/<application>/migrations/builtin/.

5 de 7

14/01/17 17:09

Hacking MAAS MAAS dev documentation

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

Performing data migration


If you need to perform data migration, very much in the same way, you will need to run Djangos makemigrations command. For
instance, if you want to perform changes to the maasserver application, run:
$ ./bin/maas-region makemigrations --empty --name description_of_the_change maasserver
This will generate a migration module named src/maasserver/migrations/builtin
/<auto_number>_description_of_the_change.py. You will need to edit that le and ll the operations list with the options that
need to be performed. Again, dont forget to add that le to the project:
$ bzr add src/maasserver/migrations/builtin/<auto_number>_description_of_the_change.py
Once the operations have been added, apply that migration with:
$ make syncdb

Migrations before MAAS 2.0


Previous version before MAAS 2.0 used South to perform database migrations. To support upgrading from any previous version of
MAAS before 2.0 the South migrations are run. On upgrade of MAAS those migrations will be run before the new Django
migrations are run. On a fresh installation of MAAS the South migrations will be skipped because the Django migrations already
provide the entire schema in the initial migration. All of this logic is performed on upgrade by the dbupgrade command.:
$ bin/maas-region dbupgrade
In some testing case you might need to always run the South migrations before the Django migrations on a clean database. Using
the always-south option on the dbupgrade command allows this testing scenario.:
$ bin/maas-region dbupgrade --always-south

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.

Examining the database manually


If you need to get an interactive psql prompt, you can use dbshell:
$ bin/maas-region dbshell
If you need to do the same thing with a version of MAAS you have installed from the package, you can use:
$ sudo maas-region dbshell --installed
You can use the \dt command to list the tables in the MAAS database. You can also execute arbitrary SQL. For example::

6 de 7

14/01/17 17:09

Hacking MAAS MAAS dev documentation

http://docs.maas.io/2.1/hacking.html

maasdb=# select system_id, hostname from maasserver_node;


system_id
|
hostname
-------------------------------------------+-------------------node-709703ec-c304-11e4-804c-00163e32e5b5 | gross-debt.local
node-7069401a-c304-11e4-a64e-00163e32e5b5 | round-attack.local
(2 rows)

Documentation
Use reST with the convention for headings as used in the Python documentation.

Updating copyright notices


Use the Bazaar Copyright Updater:
bzr branch lp:bzr-update-copyright ~/.bazaar/plugins/update_copyright
make copyright
Then commit any changes.

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

Anda mungkin juga menyukai