Merge lp:~evilnick/maas/docs-preeseed+man-page-fixes into lp:~maas-committers/maas/trunk
- docs-preeseed+man-page-fixes
- Merge into trunk
Proposed by
Nick Veitch
Status: | Rejected |
---|---|
Rejected by: | Nick Veitch |
Proposed branch: | lp:~evilnick/maas/docs-preeseed+man-page-fixes |
Merge into: | lp:~maas-committers/maas/trunk |
Diff against target: |
1559 lines (+876/-220) 4 files modified
INSTALL.txt (+104/-121) docs/configure.rst (+137/-8) docs/maascli.rst (+92/-83) docs/man/maas-cli.8.rst (+543/-8) |
To merge this branch: | bzr merge lp:~evilnick/maas/docs-preeseed+man-page-fixes |
Related bugs: |
Reviewer | Review Type | Date Requested | Status |
---|---|---|---|
Launchpad code reviewers | Pending | ||
Review via email: mp+135891@code.launchpad.net |
Commit message
added preseed docs and fixed man page links
Description of the change
added section on editing preseed
fixed man page/html clash for now
To post a comment you must log in.
Unmerged revisions
- 1369. By Nick Veitch
-
new preseed, man page fixes
Preview Diff
[H/L] Next/Prev Comment, [J/K] Next/Prev File, [N/P] Next/Prev Hunk
1 | === modified file 'INSTALL.txt' | |||
2 | --- INSTALL.txt 2012-11-20 21:46:37 +0000 | |||
3 | +++ INSTALL.txt 2012-11-23 13:00:36 +0000 | |||
4 | @@ -1,18 +1,17 @@ | |||
5 | 1 | .. -*- mode: rst -*- | 1 | .. -*- mode: rst -*- |
6 | 2 | 2 | ||
8 | 3 | 3 | ||
9 | 4 | Installing MAAS | 4 | Installing MAAS |
10 | 5 | =============== | 5 | =============== |
11 | 6 | 6 | ||
12 | 7 | There are two main ways to install MAAS | 7 | There are two main ways to install MAAS |
13 | 8 | 8 | ||
18 | 9 | * :ref:`From Ubuntu's package archive on an existing Ubuntu | 9 | * :ref:`From Ubuntu's package archive on an existing Ubuntu install. <pkg-install>` |
19 | 10 | install. <pkg-install>` | 10 | * :ref:`As a fresh install from Ubuntu Server install media. <disc-install>` |
20 | 11 | * :ref:`As a fresh install from Ubuntu Server install | 11 | |
17 | 12 | media. <disc-install>` | ||
21 | 13 | 12 | ||
24 | 14 | If you are interested in testing the latest development version you | 13 | If you are interested in testing the latest development version you can |
25 | 15 | can also check out the very latest source and build MAAS yourself. | 14 | also check out the very latest source and build MAAS yourself. |
26 | 16 | 15 | ||
27 | 17 | 16 | ||
28 | 18 | .. _pkg-install: | 17 | .. _pkg-install: |
29 | @@ -21,33 +20,29 @@ | |||
30 | 21 | -------------------------------- | 20 | -------------------------------- |
31 | 22 | 21 | ||
32 | 23 | Installing MAAS from packages is thankfully straightforward. There are | 22 | Installing MAAS from packages is thankfully straightforward. There are |
38 | 24 | actually several packages that go into making up a working MAAS | 23 | actually several packages that go into making up a working MAAS install, |
39 | 25 | install, but for convenience, many of these have been gathered into a | 24 | but for convenience, many of these have been gathered into a virtual package |
40 | 26 | virtual package called 'maas' which will install the necessary | 25 | called 'maas' which will install the necessary components for a 'seed cloud', |
41 | 27 | components for a 'seed cloud', that is a single server that will | 26 | that is a single server that will directly control a group of nodes. The main packages are: |
37 | 28 | directly control a group of nodes. The main packages are: | ||
42 | 29 | 27 | ||
45 | 30 | * ``maas`` - seed cloud setup, which includes both the region | 28 | * ``maas`` - seed cloud setup, which includes both the region controller and |
46 | 31 | controller and the cluster controller below. | 29 | the cluster controller below. |
47 | 32 | * ``maas-region-controller`` - includes the web UI, API and database. | 30 | * ``maas-region-controller`` - includes the web UI, API and database. |
50 | 33 | * ``maas-cluster-controller`` - controls a group ("cluster") of nodes | 31 | * ``maas-cluster-controller`` - controls a group ("cluster") of nodes including DHCP management. |
49 | 34 | including DHCP management. | ||
51 | 35 | * ``maas-dhcp``/``maas-dns`` - required when managing dhcp/dns. | 32 | * ``maas-dhcp``/``maas-dns`` - required when managing dhcp/dns. |
52 | 36 | 33 | ||
67 | 37 | If you need to separate these services or want to deploy an additional | 34 | If you need to separate these services or want to deploy an additional cluster |
68 | 38 | cluster controller, you should install the corresponding packages | 35 | controller, you should install the corresponding packages individually |
69 | 39 | individually (see :ref:`the description of a typical setup <setup>` | 36 | (see :ref:`the description of a typical setup <setup>` for more background |
70 | 40 | for more background on how a typical hardware setup might be | 37 | on how a typical hardware setup might be arranged). |
71 | 41 | arranged). | 38 | |
72 | 42 | 39 | There are two suggested additional packages 'maas-dhcp' and 'maas-dns'. These | |
73 | 43 | There are two suggested additional packages 'maas-dhcp' and | 40 | set up MAAS-controlled DHCP and DNS services which greatly simplify deployment |
74 | 44 | 'maas-dns'. These set up MAAS-controlled DHCP and DNS services which | 41 | if you are running a typical setup where the MAAS controller can run the |
75 | 45 | greatly simplify deployment if you are running a typical setup where | 42 | network (Note: These **must** be installed if you later set the options in |
76 | 46 | the MAAS controller can run the network (Note: These **must** be | 43 | the web interface to have MAAS manage DHCP/DNS). If you need to integrate your |
77 | 47 | installed if you later set the options in the web interface to have | 44 | MAAS setup under an existing DHCP setup, see :ref:`manual-dhcp` |
78 | 48 | MAAS manage DHCP/DNS). If you need to integrate your MAAS setup under | 45 | |
65 | 49 | an existing DHCP setup, see :ref:`manual-dhcp` | ||
66 | 50 | |||
79 | 51 | 46 | ||
80 | 52 | Install packages | 47 | Install packages |
81 | 53 | ^^^^^^^^^^^^^^^^ | 48 | ^^^^^^^^^^^^^^^^ |
82 | @@ -56,118 +51,110 @@ | |||
83 | 56 | 51 | ||
84 | 57 | $ sudo apt-get install maas maas-dhcp maas-dns | 52 | $ sudo apt-get install maas maas-dhcp maas-dns |
85 | 58 | 53 | ||
89 | 59 | You will see a list of packages and a confirmation message to | 54 | You will see a list of packages and a confirmation message to proceed. The |
90 | 60 | proceed. The exact list will obviously depend on what you already have | 55 | exact list will obviously depend on what you already have installed on your |
91 | 61 | installed on your server, but expect to add about 200MB of files. | 56 | server, but expect to add about 200MB of files. |
92 | 62 | 57 | ||
95 | 63 | The configuration for the MAAS controller will automatically run and | 58 | The configuration for the MAAS controller will automatically run and pop up |
96 | 64 | pop up this config screen: | 59 | this config screen: |
97 | 65 | 60 | ||
98 | 66 | .. image:: media/install_cluster-config.* | 61 | .. image:: media/install_cluster-config.* |
99 | 67 | 62 | ||
105 | 68 | Here you will need to enter the hostname for where the region | 63 | Here you will need to enter the hostname for where the region controller can |
106 | 69 | controller can be contacted. In many scenarios, you may be running the | 64 | be contacted. In many scenarios, you may be running the region controller |
107 | 70 | region controller (i.e. the web and API interface) from a different | 65 | (i.e. the web and API interface) from a different network address, for example |
108 | 71 | network address, for example where a server has several network | 66 | where a server has several network interfaces. |
104 | 72 | interfaces. | ||
109 | 73 | 67 | ||
112 | 74 | Once the configuration scripts have run you should see this message | 68 | Once the configuration scripts have run you should see this message telling |
113 | 75 | telling you that the system is ready to use: | 69 | you that the system is ready to use: |
114 | 76 | 70 | ||
115 | 77 | .. image:: media/install_controller-config.* | 71 | .. image:: media/install_controller-config.* |
116 | 78 | 72 | ||
121 | 79 | The web server is started last, so you have to accept this message | 73 | The web server is started last, so you have to accept this message before the service is run and you can access the Web interface. Then there are just a few |
122 | 80 | before the service is run and you can access the Web interface. Then | 74 | more setup steps :ref:`post_install` |
119 | 81 | there are just a few more setup steps :ref:`post_install` | ||
120 | 82 | |||
123 | 83 | 75 | ||
124 | 84 | .. _disc-install: | 76 | .. _disc-install: |
125 | 85 | 77 | ||
126 | 86 | Installing MAAS from Ubuntu Server boot media | 78 | Installing MAAS from Ubuntu Server boot media |
127 | 87 | --------------------------------------------- | 79 | --------------------------------------------- |
128 | 88 | 80 | ||
133 | 89 | If you are installing MAAS as part of a fresh install it is easiest to | 81 | If you are installing MAAS as part of a fresh install it is easiest to choose |
134 | 90 | choose the "Multiple Server install with MAAS" option from the | 82 | the "Multiple Server install with MAAS" option from the installer and have |
135 | 91 | installer and have pretty much everything set up for you. Boot from | 83 | pretty much everything set up for you. |
136 | 92 | the Ubuntu Server media and you will be greeted with the usual | 84 | Boot from the Ubuntu Server media and you will be greeted with the usual |
137 | 93 | language selection screen: | 85 | language selection screen: |
138 | 94 | 86 | ||
139 | 95 | .. image:: media/install_01.* | 87 | .. image:: media/install_01.* |
140 | 96 | 88 | ||
144 | 97 | On the next screen, you will see there is an entry in the menu called | 89 | On the next screen, you will see there is an entry in the menu called "Multiple |
145 | 98 | "Multiple server install with MAAS". Use the cursor keys to select | 90 | server install with MAAS". Use the cursor keys to select this and then press |
146 | 99 | this and then press Enter. | 91 | Enter. |
147 | 100 | 92 | ||
148 | 101 | .. image:: media/install_02.* | 93 | .. image:: media/install_02.* |
149 | 102 | 94 | ||
154 | 103 | The installer then runs through the usual language and keyboard | 95 | The installer then runs through the usual language and keyboard options. Make |
155 | 104 | options. Make your selections using Tab/Cursor keys/Enter to proceed | 96 | your selections using Tab/Cursor keys/Enter to proceed through the install. |
156 | 105 | through the install. The installer will then load various drivers, | 97 | The installer will then load various drivers, which may take a moment or two. |
153 | 106 | which may take a moment or two. | ||
157 | 107 | 98 | ||
158 | 108 | .. image:: media/install_03.* | 99 | .. image:: media/install_03.* |
159 | 109 | 100 | ||
162 | 110 | The next screen asks for the hostname for this server. Choose | 101 | The next screen asks for the hostname for this server. Choose something |
163 | 111 | something appropriate for your network. | 102 | appropriate for your network. |
164 | 103 | |||
165 | 112 | 104 | ||
166 | 113 | .. image:: media/install_04.* | 105 | .. image:: media/install_04.* |
167 | 114 | 106 | ||
171 | 115 | Finally we get to the MAAS part! Here there are just two options. We | 107 | Finally we get to the MAAS part! Here there are just two options. We want to |
172 | 116 | want to "Create a new MAAS on this server" so go ahead and choose that | 108 | "Create a new MAAS on this server" so go ahead and choose that one. |
170 | 117 | one. | ||
173 | 118 | 109 | ||
174 | 119 | .. image:: media/install_05.* | 110 | .. image:: media/install_05.* |
175 | 120 | 111 | ||
179 | 121 | The install now continues as usual. Next you will be prompted to enter | 112 | The install now continues as usual. Next you will be prompted to enter a |
180 | 122 | a username. This will be the admin user for the actual server that | 113 | username. This will be the admin user for the actual server that MAAS will |
181 | 123 | MAAS will be running on (not the same as the MAAS admin user!) | 114 | be running on (not the same as the MAAS admin user!) |
182 | 124 | 115 | ||
183 | 125 | .. image:: media/install_06.* | 116 | .. image:: media/install_06.* |
184 | 126 | 117 | ||
188 | 127 | As usual you will have the chance to encrypt your home | 118 | As usual you will have the chance to encrypt your home directory. Continue |
189 | 128 | directory. Continue to make selections based on whatever settings suit | 119 | to make selections based on whatever settings suit your usage. |
187 | 129 | your usage. | ||
190 | 130 | 120 | ||
191 | 131 | .. image:: media/install_07.* | 121 | .. image:: media/install_07.* |
192 | 132 | 122 | ||
195 | 133 | After making selections and partitioning storage, the system software | 123 | After making selections and partitioning storage, the system software will |
196 | 134 | will start to be installed. This part should only take a few minutes. | 124 | start to be installed. This part should only take a few minutes. |
197 | 135 | 125 | ||
198 | 136 | .. image:: media/install_09.* | 126 | .. image:: media/install_09.* |
199 | 137 | 127 | ||
204 | 138 | Various packages will now be configured, including the package manager | 128 | Various packages will now be configured, including the package manager and |
205 | 139 | and update manager. It is important to set these up appropriately so | 129 | update manager. It is important to set these up appropriately so you will |
206 | 140 | you will receive timely updates of the MAAS server software, as well | 130 | receive timely updates of the MAAS server software, as well as other essential services that may run on this server. |
203 | 141 | as other essential services that may run on this server. | ||
207 | 142 | 131 | ||
208 | 143 | .. image:: media/install_10.* | 132 | .. image:: media/install_10.* |
209 | 144 | 133 | ||
214 | 145 | The configuration for MAAS will ask you to configure the host address | 134 | The configuration for MAAS will ask you to configure the host address of the |
215 | 146 | of the server. This should be the IP address you will use to connect | 135 | server. This should be the IP address you will use to connect to the server |
216 | 147 | to the server (you may have additional interfaces e.g. to run node | 136 | (you may have additional interfaces e.g. to run node subnets) |
213 | 148 | subnets) | ||
217 | 149 | 137 | ||
218 | 150 | .. image:: media/install_cluster-config.* | 138 | .. image:: media/install_cluster-config.* |
219 | 151 | 139 | ||
222 | 152 | The next screen will confirm the web address that will be used to the | 140 | The next screen will confirm the web address that will be used to the web |
223 | 153 | web interface. | 141 | interface. |
224 | 154 | 142 | ||
225 | 155 | .. image:: media/install_controller-config.* | 143 | .. image:: media/install_controller-config.* |
226 | 156 | 144 | ||
229 | 157 | After configuring any other packages the installer will finally come | 145 | After configuring any other packages the installer will finally come to and |
230 | 158 | to and end. At this point you should eject the boot media. | 146 | end. At this point you should eject the boot media. |
231 | 159 | 147 | ||
232 | 160 | .. image:: media/install_14.* | 148 | .. image:: media/install_14.* |
233 | 161 | 149 | ||
237 | 162 | After restarting, you should be able to login to the new server with | 150 | After restarting, you should be able to login to the new server with the |
238 | 163 | the information you supplied during the install. The MAAS software | 151 | information you supplied during the install. The MAAS software will run automatically. |
239 | 164 | will run automatically. | 152 | |
240 | 165 | 153 | ||
241 | 166 | .. image:: media/install_15.* | 154 | .. image:: media/install_15.* |
242 | 167 | 155 | ||
246 | 168 | **NOTE:** The maas-dhcp and maas-dns packages are not installed by | 156 | |
247 | 169 | default. If you want to have MAAS run DHCP and DNS services, you | 157 | **NOTE:** The maas-dhcp and maas-dns packages are not installed by default. If you want to have MAAS run DHCP and DNS services, you should install these packages:: |
245 | 170 | should install these packages:: | ||
248 | 171 | 158 | ||
249 | 172 | $ sudo apt-get install maas-dhcp maas-dns | 159 | $ sudo apt-get install maas-dhcp maas-dns |
250 | 173 | 160 | ||
251 | @@ -175,19 +162,15 @@ | |||
252 | 175 | 162 | ||
253 | 176 | .. _post_install: | 163 | .. _post_install: |
254 | 177 | 164 | ||
255 | 178 | |||
256 | 179 | Post-Install tasks | 165 | Post-Install tasks |
257 | 180 | ================== | 166 | ================== |
262 | 181 | 167 | If you now use a web browser to connect to the region controller, you should | |
263 | 182 | If you now use a web browser to connect to the region controller, you | 168 | see that MAAS is running, but there will also be some errors on the screen: |
260 | 183 | should see that MAAS is running, but there will also be some errors on | ||
261 | 184 | the screen: | ||
264 | 185 | 169 | ||
265 | 186 | .. image:: media/install_web-init.* | 170 | .. image:: media/install_web-init.* |
266 | 187 | 171 | ||
270 | 188 | The on screen messages will tell you that there are no boot images | 172 | The on screen messages will tell you that there are no boot images present, |
271 | 189 | present, and that you can't login because there is no admin user. | 173 | and that you can't login because there is no admin user. |
269 | 190 | |||
272 | 191 | 174 | ||
273 | 192 | Create a superuser account | 175 | Create a superuser account |
274 | 193 | -------------------------- | 176 | -------------------------- |
275 | @@ -197,37 +180,35 @@ | |||
276 | 197 | 180 | ||
277 | 198 | $ sudo maas createsuperuser | 181 | $ sudo maas createsuperuser |
278 | 199 | 182 | ||
284 | 200 | Follow the prompts to create the account which you will need to login | 183 | Follow the prompts to create the account which you will need to |
285 | 201 | to the web interface. Unless you have a special need, it is best to | 184 | login to the web interface. Unless you have a special need, it is best to |
286 | 202 | accept the default login name of `root`, as it is rather annoying if | 185 | accept the default login name of `root`, as it is rather annoying if you |
287 | 203 | you forget the username (although you can simply run this command | 186 | forget the username (although you can simply run this command again to create |
288 | 204 | again to create a new superuser). | 187 | a new superuser). |
289 | 205 | 188 | ||
290 | 206 | 189 | ||
291 | 207 | Import the boot images | 190 | Import the boot images |
292 | 208 | ---------------------- | 191 | ---------------------- |
293 | 209 | 192 | ||
294 | 210 | MAAS will check for and download new Ubuntu images once a week. | 193 | MAAS will check for and download new Ubuntu images once a week. |
306 | 211 | However, you'll need to download them manually the first time. To do | 194 | However, you'll need to download them manually the first time:: |
307 | 212 | this you will need to connect to the MAAS API using the maas-cli | 195 | |
308 | 213 | tool. (see :ref:`Logging in <api-key>` for details). Then you need to | 196 | $ sudo maas-import-pxe-files |
309 | 214 | run the command:: | 197 | |
310 | 215 | 198 | If you are using an HTTP proxy, bear in mind that the "sudo" will not | |
311 | 216 | $ maas-cli maas node-groups import-boot-images | 199 | pass your http_proxy environment variable on to the script. If that is |
312 | 217 | 200 | a problem, pass it on explicitly:: | |
313 | 218 | (substitute in a different profile name for 'maas' if you have called | 201 | |
314 | 219 | yours something else) This will initiate downloading the required | 202 | $ sudo http_proxy=$http_proxy maas-import-pxe-files |
304 | 220 | image files. Note that this may take some time depending on your | ||
305 | 221 | network connection. | ||
315 | 222 | 203 | ||
316 | 223 | 204 | ||
317 | 224 | Login to the server | 205 | Login to the server |
318 | 225 | ------------------- | 206 | ------------------- |
319 | 226 | 207 | ||
324 | 227 | To check that everything is working properly, you should try and login | 208 | To check that everything is working properly, you should try and login to |
325 | 228 | to the server now. Both the error messages should have gone (it can | 209 | the server now. Both the error messages should have gone (it can take a |
326 | 229 | take a few minutes for the boot image files to register) and you can | 210 | few minutes for the boot image files to register) and you can see that |
327 | 230 | see that there are currently 0 nodes attached to this controller. | 211 | there are currently 0 nodes attached to this controller. |
328 | 231 | 212 | ||
329 | 232 | .. image:: media/install-login.* | 213 | .. image:: media/install-login.* |
330 | 233 | 214 | ||
331 | @@ -235,9 +216,11 @@ | |||
332 | 235 | Configure DHCP | 216 | Configure DHCP |
333 | 236 | -------------- | 217 | -------------- |
334 | 237 | 218 | ||
338 | 238 | If you are using MAAS to control DHCP, you need to set this via the | 219 | If you are using MAAS to control DHCP, you need to configure this using the |
339 | 239 | web interface. However, if you are manually configuring a DHCP | 220 | commandline interface, first by :ref:`logging on to the server API <api-key>` |
340 | 240 | server, you should take a look at :ref:`manual-dhcp` | 221 | and then :ref:`setting up the interface <cli-dhcp>` |
341 | 222 | However, if you are manually configuring a DHCP server, you should take a | ||
342 | 223 | look at :ref:`manual-dhcp` | ||
343 | 241 | 224 | ||
346 | 242 | Once everything is set up and running, you are ready to :doc:`start | 225 | Once everything is set up and running, you are ready to :doc:`start enlisting |
347 | 243 | enlisting nodes <nodes>` | 226 | nodes <nodes>` |
348 | 244 | 227 | ||
349 | === modified file 'docs/configure.rst' | |||
350 | --- docs/configure.rst 2012-11-22 03:18:35 +0000 | |||
351 | +++ docs/configure.rst 2012-11-23 13:00:36 +0000 | |||
352 | @@ -1,22 +1,23 @@ | |||
353 | 1 | Additional Configuration | 1 | Additional Configuration |
354 | 2 | ======================== | 2 | ======================== |
355 | 3 | 3 | ||
356 | 4 | |||
357 | 5 | .. _manual-dhcp: | 4 | .. _manual-dhcp: |
358 | 6 | 5 | ||
359 | 7 | Manual DHCP configuration | 6 | Manual DHCP configuration |
360 | 8 | ------------------------- | 7 | ------------------------- |
361 | 9 | 8 | ||
366 | 10 | There are some circumstances under which you may not wish the master | 9 | There are some circumstances under which you may not wish the master MAAS |
367 | 11 | MAAS worker to handle DHCP for the network. In these instances, the | 10 | worker to handle DHCP for the network. In these instances, the existing DHCP |
368 | 12 | existing DHCP server for the network will need its configuration | 11 | server for the network will need its configuration altered to allow MAAS to |
369 | 13 | altered to allow MAAS to enlist and control nodes automatically. | 12 | enlist and control nodes automatically. |
370 | 14 | 13 | ||
372 | 15 | At the very least the filename should be set to pxelinux.0. | 14 | At the very least the next-server should point to the MAAS controller host |
373 | 15 | address and the filename should be set to pxelinux.0 | ||
374 | 16 | 16 | ||
375 | 17 | The configuration entry may look something like this:: | 17 | The configuration entry may look something like this:: |
376 | 18 | 18 | ||
377 | 19 | subnet 192.168.122.0 netmask 255.255.255.0 { | 19 | subnet 192.168.122.0 netmask 255.255.255.0 { |
378 | 20 | next-server 192.168.122.136; | ||
379 | 20 | filename "pxelinux.0"; | 21 | filename "pxelinux.0"; |
380 | 21 | option subnet-mask 255.255.255.0; | 22 | option subnet-mask 255.255.255.0; |
381 | 22 | option broadcast-address 192.168.122.255; | 23 | option broadcast-address 192.168.122.255; |
382 | @@ -24,12 +25,10 @@ | |||
383 | 24 | range dynamic-bootp 192.168.122.5 192.168.122.135; | 25 | range dynamic-bootp 192.168.122.5 192.168.122.135; |
384 | 25 | } | 26 | } |
385 | 26 | 27 | ||
386 | 27 | |||
387 | 28 | .. _ssl: | 28 | .. _ssl: |
388 | 29 | 29 | ||
389 | 30 | SSL Support | 30 | SSL Support |
390 | 31 | ----------- | 31 | ----------- |
391 | 32 | |||
392 | 33 | If you want secure access to your MAAS web UI/API, you need to do a few | 32 | If you want secure access to your MAAS web UI/API, you need to do a few |
393 | 34 | things. First, turn on SSL support in Apache:: | 33 | things. First, turn on SSL support in Apache:: |
394 | 35 | 34 | ||
395 | @@ -48,3 +47,133 @@ | |||
396 | 48 | the default SSL certificate is insecure. Please generate your own and then | 47 | the default SSL certificate is insecure. Please generate your own and then |
397 | 49 | edit ``/etc/apache2/conf.d/maas-http.conf`` to set the location of the | 48 | edit ``/etc/apache2/conf.d/maas-http.conf`` to set the location of the |
398 | 50 | certificate. | 49 | certificate. |
399 | 50 | |||
400 | 51 | |||
401 | 52 | Choosing a series to install | ||
402 | 53 | ---------------------------- | ||
403 | 54 | |||
404 | 55 | You may have some specific reason to choose a particular version of Ubuntu | ||
405 | 56 | to install on your nodes, perhaps based around package avaiability, | ||
406 | 57 | hardware support or some other reason. | ||
407 | 58 | It is possible to choose a specific series from those available in a | ||
408 | 59 | number of ways. | ||
409 | 60 | |||
410 | 61 | From the user interface | ||
411 | 62 | ^^^^^^^^^^^^^^^^^^^^^^^ | ||
412 | 63 | |||
413 | 64 | For individual nodes it is a straightforward task to select the Ubuntu | ||
414 | 65 | series to install from the user interface. When either adding a node | ||
415 | 66 | manually, or on the node page when the node has been automatically | ||
416 | 67 | discovered but before it is accepted, there is a drop down menu to select | ||
417 | 68 | the version of Ubuntu you wish to install. | ||
418 | 69 | |||
419 | 70 | .. image:: media/series.* | ||
420 | 71 | |||
421 | 72 | The menu will always list all the currently available series according | ||
422 | 73 | to which images are available. | ||
423 | 74 | |||
424 | 75 | Using the maas-cli command | ||
425 | 76 | ^^^^^^^^^^^^^^^^^^^^^^^^^^ | ||
426 | 77 | |||
427 | 78 | It is also possible to select a series using the maas-cli command. This | ||
428 | 79 | can be done on a per node basis with:: | ||
429 | 80 | |||
430 | 81 | $ maas-cli <profile> node update <system_id> distro_series="<value>" | ||
431 | 82 | |||
432 | 83 | Where the string contains one of the valid, available distro series, or | ||
433 | 84 | is empty for the default value. | ||
434 | 85 | |||
435 | 86 | |||
436 | 87 | .. _preseed: | ||
437 | 88 | |||
438 | 89 | Altering the Preseed file | ||
439 | 90 | ------------------------- | ||
440 | 91 | |||
441 | 92 | .. warning:: | ||
442 | 93 | Do not try to alter the preseed files if you don't have a good | ||
443 | 94 | understanding of what you are doing. Altering the installed version | ||
444 | 95 | of Ubuntu can prevent MAAS from working as intended, and may have | ||
445 | 96 | security and stability consequences. | ||
446 | 97 | |||
447 | 98 | When MAAS commissions a node it installs a version of Ubuntu. The | ||
448 | 99 | installation is performed using a 'preseed' file, which is | ||
449 | 100 | effectively a list of answers to the questions you would get were | ||
450 | 101 | you to run the installer manually. | ||
451 | 102 | The preseed file used by MAAS is carefully made so that the | ||
452 | 103 | target node can be brought up and do all the jobs expected of it. | ||
453 | 104 | However, in exceptional circumstances, you may wish to alter the | ||
454 | 105 | pressed file to work around some issue. | ||
455 | 106 | There are actually two preseed files, stored here:: | ||
456 | 107 | |||
457 | 108 | /usr/share/maas/preseeds/generic | ||
458 | 109 | /usr/share/maas/preseeds/preseed-master | ||
459 | 110 | |||
460 | 111 | The generic file actually references the preseed-master file, and is | ||
461 | 112 | used to set conditional parameters based on the type of series and | ||
462 | 113 | architecture to install as well as to define the minimum set of install | ||
463 | 114 | packages and to tidy up the PXE boot process if that has been used for | ||
464 | 115 | the node. Unless you have a specific need to change where install | ||
465 | 116 | packages come from, you should not need to edit this file. | ||
466 | 117 | |||
467 | 118 | For the more usual sorts of things you may wish to change, you should | ||
468 | 119 | edit the preseed-master file. For example, depending on your network | ||
469 | 120 | you may wish to change the clock settings:: | ||
470 | 121 | |||
471 | 122 | # Local clock (set to UTC and use ntp) | ||
472 | 123 | d-i clock-setup/utc boolean true | ||
473 | 124 | d-i clock-setup/ntp boolean true | ||
474 | 125 | d-i clock-setup/ntp-server string ntp.ubuntu.com | ||
475 | 126 | |||
476 | 127 | Having consistent clocks is very important to the working of your MAAS | ||
477 | 128 | system overall. If your nodes however cannot freely access the internet, | ||
478 | 129 | the supplied ntp server is not going to be very useful, and you may | ||
479 | 130 | find it better to run an ntp service on the MAAS controller and substitute | ||
480 | 131 | `ntp.ubuntu.com` in the last line for something else. | ||
481 | 132 | |||
482 | 133 | One thing you may wish to alter in the preseed file is the disk | ||
483 | 134 | partitioning. This is a simple recipe that creates a swap partition and | ||
484 | 135 | uses the rest of the disk for one large root filesystem:: | ||
485 | 136 | |||
486 | 137 | partman-auto/text/atomic_scheme :: | ||
487 | 138 | |||
488 | 139 | 500 10000 1000000 ext3 | ||
489 | 140 | $primary{ } | ||
490 | 141 | $bootable{ } | ||
491 | 142 | method{ format } | ||
492 | 143 | format{ } | ||
493 | 144 | use_filesystem{ } | ||
494 | 145 | filesystem{ ext3 } | ||
495 | 146 | mountpoint{ / } . | ||
496 | 147 | |||
497 | 148 | 64 512 300% linux-swap | ||
498 | 149 | method{ swap } | ||
499 | 150 | format{ } . | ||
500 | 151 | |||
501 | 152 | |||
502 | 153 | Here the root partition must be at least 500 mb, and has effectively no | ||
503 | 154 | maximum size. The swap partition ranges from 64 mb to 3 times the system's | ||
504 | 155 | ram. | ||
505 | 156 | Adding `$bootable{ }` to make the partition bootable, and $primary{ } | ||
506 | 157 | marks it as the primary partition. The other specifiers used are: | ||
507 | 158 | |||
508 | 159 | *method{ format }* | ||
509 | 160 | Used to make the partition be formatted. For swap partitions, | ||
510 | 161 | change it to "swap". To create a new partition but do not | ||
511 | 162 | format it, change "format" to "keep" (such a partition can be | ||
512 | 163 | used to reserve for future use some disk space). | ||
513 | 164 | *format{ }* | ||
514 | 165 | Also needed to make the partition be formatted. | ||
515 | 166 | *use_filesystem{ }* | ||
516 | 167 | Specifies that the partition has a filesystem on it. | ||
517 | 168 | *filesystem{ ext3 }* | ||
518 | 169 | Specifies the filesystem to put on the partition. | ||
519 | 170 | *mountpoint{ / }* | ||
520 | 171 | Where to mount the partition. | ||
521 | 172 | |||
522 | 173 | For more information on preseed option, you should refer to | ||
523 | 174 | `the official Ubuntu documentation <https://help.ubuntu.com/12.04/installation-guide/i386/preseed-contents.html>`_ | ||
524 | 175 | |||
525 | 176 | .. note:: | ||
526 | 177 | Future versions of MAAS are likely to replace this type of automatic | ||
527 | 178 | installation with a different installer. | ||
528 | 179 | |||
529 | 51 | 180 | ||
530 | === modified file 'docs/maascli.rst' | |||
531 | --- docs/maascli.rst 2012-11-20 21:46:37 +0000 | |||
532 | +++ docs/maascli.rst 2012-11-23 13:00:36 +0000 | |||
533 | @@ -1,9 +1,9 @@ | |||
534 | 1 | |||
535 | 1 | As well as the web interface, many tasks can be performed by accessing | 2 | As well as the web interface, many tasks can be performed by accessing |
536 | 2 | the MAAS API directly through the maas-cli command. This section | 3 | the MAAS API directly through the maas-cli command. This section |
537 | 3 | details how to login with this tool and perform some common | 4 | details how to login with this tool and perform some common |
538 | 4 | operations. | 5 | operations. |
539 | 5 | 6 | ||
540 | 6 | |||
541 | 7 | .. _api-key: | 7 | .. _api-key: |
542 | 8 | 8 | ||
543 | 9 | Logging in | 9 | Logging in |
544 | @@ -19,7 +19,7 @@ | |||
545 | 19 | .. only:: html | 19 | .. only:: html |
546 | 20 | .. image:: media/maascli-prefs.* | 20 | .. image:: media/maascli-prefs.* |
547 | 21 | 21 | ||
549 | 22 | A new page will load... | 22 | A new page will load... |
550 | 23 | 23 | ||
551 | 24 | .. only:: html | 24 | .. only:: html |
552 | 25 | .. image:: media/maascli-key.* | 25 | .. image:: media/maascli-key.* |
553 | @@ -31,21 +31,21 @@ | |||
554 | 31 | 31 | ||
555 | 32 | $ maas-cli login <profile-name> <hostname> <key> | 32 | $ maas-cli login <profile-name> <hostname> <key> |
556 | 33 | 33 | ||
560 | 34 | The profile created is an easy way of associating your credentials | 34 | The profile created is an easy way of associating your credentials with any |
561 | 35 | with any subsequent call to the API. So an example login might look | 35 | subsequent call to the API. So an example login might look like this:: |
559 | 36 | like this:: | ||
562 | 37 | 36 | ||
563 | 38 | $ maas-cli login maas http://10.98.0.13/MAAS/api/1.0 AWSCRMzqMNy:jjk...5e1FenoP82Qm5te2 | 37 | $ maas-cli login maas http://10.98.0.13/MAAS/api/1.0 AWSCRMzqMNy:jjk...5e1FenoP82Qm5te2 |
564 | 39 | 38 | ||
574 | 40 | which creates the profile 'maas' and registers it with the given key | 39 | which creates the profile 'maas' and registers it with the given key at the |
575 | 41 | at the specified API endpoint. If you omit the credentials, they will | 40 | specified API endpoint. |
576 | 42 | be prompted for in the console. It is also possible to use a hyphen, | 41 | If you omit the credentials, they will be prompted for in the console. It is |
577 | 43 | '-' in place of the credentials. In this case a single line will be | 42 | also possible to use a hyphen, '-' in place of the credentials. In this case a |
578 | 44 | read from stdin, stripped of any whitespace and used as the | 43 | single line will be read from stdin, stripped of any whitespace and used as the |
579 | 45 | credentials, which can be useful if you are devolping scripts for | 44 | credentials, which can be useful if you are devolping scripts for specific |
580 | 46 | specific tasks. If an empty string is passed instead of the | 45 | tasks. |
581 | 47 | credentials, the profile will be logged in anonymously (and | 46 | If an empty string is passed instead of the credentials, the profile will be |
582 | 48 | consequently some of the API calls will not be available) | 47 | logged in anonymously (and consequently some of the API calls will not be |
583 | 48 | available) | ||
584 | 49 | 49 | ||
585 | 50 | 50 | ||
586 | 51 | maas-cli commands | 51 | maas-cli commands |
587 | @@ -77,7 +77,7 @@ | |||
588 | 77 | Logs in to the MAAS controller API at the given URL, using the key | 77 | Logs in to the MAAS controller API at the given URL, using the key |
589 | 78 | provided and associates this connection with the given profile name. | 78 | provided and associates this connection with the given profile name. |
590 | 79 | 79 | ||
592 | 80 | :samp:`logout <profile>` | 80 | :samp:`logout <profile>` |
593 | 81 | 81 | ||
594 | 82 | Logs out from the given profile, flushing the stored credentials. | 82 | Logs out from the given profile, flushing the stored credentials. |
595 | 83 | 83 | ||
596 | @@ -108,12 +108,12 @@ | |||
597 | 108 | :samp:`-d, --debug` | 108 | :samp:`-d, --debug` |
598 | 109 | 109 | ||
599 | 110 | Displays debug information listing the API responses. | 110 | Displays debug information listing the API responses. |
601 | 111 | 111 | ||
602 | 112 | :samp:`-h, --help` | 112 | :samp:`-h, --help` |
603 | 113 | 113 | ||
604 | 114 | Display usage information. | 114 | Display usage information. |
605 | 115 | 115 | ||
607 | 116 | :samp:`-k, --insecure` | 116 | :samp:`-k, --insecure` |
608 | 117 | 117 | ||
609 | 118 | Disables the SSL certificate check. | 118 | Disables the SSL certificate check. |
610 | 119 | 119 | ||
611 | @@ -127,6 +127,8 @@ | |||
612 | 127 | Removes the given key from the list of authorisation tokens. | 127 | Removes the given key from the list of authorisation tokens. |
613 | 128 | 128 | ||
614 | 129 | 129 | ||
615 | 130 | |||
616 | 131 | |||
617 | 130 | .. boot-images - not useful in user context | 132 | .. boot-images - not useful in user context |
618 | 131 | .. ^^^^^^^^^^^ | 133 | .. ^^^^^^^^^^^ |
619 | 132 | 134 | ||
620 | @@ -157,50 +159,54 @@ | |||
621 | 157 | Releases the node given by *<system_id>* | 159 | Releases the node given by *<system_id>* |
622 | 158 | 160 | ||
623 | 159 | :samp:`start <system_id>` | 161 | :samp:`start <system_id>` |
625 | 160 | 162 | ||
626 | 161 | Powers up the node identified by *<system_id>* (where MAAS has | 163 | Powers up the node identified by *<system_id>* (where MAAS has |
627 | 162 | information for power management for this node). | 164 | information for power management for this node). |
628 | 163 | 165 | ||
629 | 164 | :samp:`stop <system_id>` | 166 | :samp:`stop <system_id>` |
631 | 165 | 167 | ||
632 | 166 | Powers off the node identified by *<system_id>* (where MAAS has | 168 | Powers off the node identified by *<system_id>* (where MAAS has |
633 | 167 | information for power management for this node). | 169 | information for power management for this node). |
634 | 168 | 170 | ||
635 | 169 | :samp:`delete <system_id>` | 171 | :samp:`delete <system_id>` |
637 | 170 | 172 | ||
638 | 171 | Removes the given node from the MAAS database. | 173 | Removes the given node from the MAAS database. |
639 | 172 | 174 | ||
640 | 173 | :samp:`read <system_id>` | 175 | :samp:`read <system_id>` |
642 | 174 | 176 | ||
643 | 175 | Returns all the current known information about the node specified | 177 | Returns all the current known information about the node specified |
644 | 176 | by *<system_id>* | 178 | by *<system_id>* |
645 | 177 | 179 | ||
646 | 178 | :samp:`update <system_id> [parameters...]` | 180 | :samp:`update <system_id> [parameters...]` |
648 | 179 | 181 | ||
649 | 180 | Used to change or set specific values for the node. The valid | 182 | Used to change or set specific values for the node. The valid |
650 | 181 | parameters are listed below:: | 183 | parameters are listed below:: |
651 | 182 | 184 | ||
652 | 183 | hostname=<value> | 185 | hostname=<value> |
653 | 184 | The new hostname for this node. | 186 | The new hostname for this node. |
654 | 185 | 187 | ||
656 | 186 | architecture=<value> | 188 | architecture=<value> |
657 | 187 | Sets the architecture type, where <value> | 189 | Sets the architecture type, where <value> |
658 | 188 | is a string containing a valid architecture type, | 190 | is a string containing a valid architecture type, |
659 | 189 | e.g. "i386/generic" | 191 | e.g. "i386/generic" |
660 | 190 | 192 | ||
667 | 191 | power_type=<value> | 193 | distro_series=<value> |
668 | 192 | Apply the given dotted decimal value as the broadcast IP address | 194 | Sets the series of Ubuntu to use. |
669 | 193 | for this subnet. | 195 | |
670 | 194 | 196 | power_type=<value> | |
671 | 195 | power_parameters_{param1}... =<value> | 197 | Sets the type of power management used on the node, e.g. "ipmi" or |
672 | 196 | Set the given power parameters. Note that the valid options for these | 198 | "virsh". |
673 | 199 | |||
674 | 200 | power_parameters_{param1}... =<value> | ||
675 | 201 | Set the given power parameters. Note that the valid options for these | ||
676 | 197 | depend on the power type chosen. | 202 | depend on the power type chosen. |
677 | 198 | 203 | ||
680 | 199 | power_parameters_skip_check 'true' | 'false' | 204 | power_parameters_skip_check 'true' | 'false' |
681 | 200 | Whether to sanity check the supplied parameters against this node's | 205 | Whether to sanity check the supplied parameters against this node's |
682 | 201 | declared power type. The default is 'false'. | 206 | declared power type. The default is 'false'. |
683 | 202 | 207 | ||
684 | 203 | 208 | ||
685 | 209 | |||
686 | 204 | .. _cli-power: | 210 | .. _cli-power: |
687 | 205 | 211 | ||
688 | 206 | Example: Setting the power parameters for an ipmi enabled node:: | 212 | Example: Setting the power parameters for an ipmi enabled node:: |
689 | @@ -212,6 +218,8 @@ | |||
690 | 212 | power_parameters_power_pass=ubuntu; | 218 | power_parameters_power_pass=ubuntu; |
691 | 213 | 219 | ||
692 | 214 | 220 | ||
693 | 221 | |||
694 | 222 | |||
695 | 215 | nodes | 223 | nodes |
696 | 216 | ^^^^^ | 224 | ^^^^^ |
697 | 217 | 225 | ||
698 | @@ -291,6 +299,7 @@ | |||
699 | 291 | $ maas-cli maas nodes list architecture="i386/generic" | 299 | $ maas-cli maas nodes list architecture="i386/generic" |
700 | 292 | 300 | ||
701 | 293 | 301 | ||
702 | 302 | |||
703 | 294 | node-groups | 303 | node-groups |
704 | 295 | ^^^^^^^^^^^ | 304 | ^^^^^^^^^^^ |
705 | 296 | Usage: maas-cli <profile> node-groups [-d --debug] [-h --help] [-k | 305 | Usage: maas-cli <profile> node-groups [-d --debug] [-h --help] [-k |
706 | @@ -301,7 +310,7 @@ | |||
707 | 301 | :samp:`-d, --debug` | 310 | :samp:`-d, --debug` |
708 | 302 | 311 | ||
709 | 303 | Displays debug information listing the API responses. | 312 | Displays debug information listing the API responses. |
711 | 304 | 313 | ||
712 | 305 | :samp:`-h, --help` | 314 | :samp:`-h, --help` |
713 | 306 | 315 | ||
714 | 307 | Display usage information. | 316 | Display usage information. |
715 | @@ -311,7 +320,7 @@ | |||
716 | 311 | Disables the SSL certificate check. | 320 | Disables the SSL certificate check. |
717 | 312 | 321 | ||
718 | 313 | :samp:`register uuid=<value> name=<value> interfaces=<json_string>` | 322 | :samp:`register uuid=<value> name=<value> interfaces=<json_string>` |
720 | 314 | 323 | ||
721 | 315 | Registers a new node group with the given name and uuid. The | 324 | Registers a new node group with the given name and uuid. The |
722 | 316 | interfaces parameter must be supplied in the form of a JSON string | 325 | interfaces parameter must be supplied in the form of a JSON string |
723 | 317 | comprising the key/value data for the interface to be used, for | 326 | comprising the key/value data for the interface to be used, for |
724 | @@ -322,7 +331,7 @@ | |||
725 | 322 | 331 | ||
726 | 323 | :samp:`list` | 332 | :samp:`list` |
727 | 324 | 333 | ||
729 | 325 | Returns a JSON list of all currently defined node groups. | 334 | Returns a JSON list of all currently defined node groups. |
730 | 326 | 335 | ||
731 | 327 | :samp:`refresh_workers` | 336 | :samp:`refresh_workers` |
732 | 328 | 337 | ||
733 | @@ -333,7 +342,7 @@ | |||
734 | 333 | nodes. | 342 | nodes. |
735 | 334 | 343 | ||
736 | 335 | :samp:`accept <uuid>` | 344 | :samp:`accept <uuid>` |
738 | 336 | 345 | ||
739 | 337 | Accepts a node-group or number of nodegroups indicated by the | 346 | Accepts a node-group or number of nodegroups indicated by the |
740 | 338 | supplied UUID | 347 | supplied UUID |
741 | 339 | 348 | ||
742 | @@ -343,60 +352,62 @@ | |||
743 | 343 | supplied UUID | 352 | supplied UUID |
744 | 344 | 353 | ||
745 | 345 | 354 | ||
746 | 355 | |||
747 | 346 | node-group-interface | 356 | node-group-interface |
748 | 347 | ^^^^^^^^^^^^^^^^^^^^ | 357 | ^^^^^^^^^^^^^^^^^^^^ |
750 | 348 | For managing the interfaces. See also :ref:`node-group-interfaces` | 358 | For managing the interfaces. See also |
751 | 359 | :ref:`node_group_interfaces <node_group_interfaces>` | ||
752 | 349 | 360 | ||
754 | 350 | Usage: maas-cli *<profile>* node-group-interfaces [-d --debug] [-h | 361 | Usage: maas-cli *<profile>* node-group-interface [-d --debug] [-h |
755 | 351 | --help] [-k --insecure] read | update | delete [parameters...] | 362 | --help] [-k --insecure] read | update | delete [parameters...] |
756 | 352 | 363 | ||
757 | 353 | ..program:: maas-cli node-group-interface | 364 | ..program:: maas-cli node-group-interface |
758 | 354 | 365 | ||
759 | 355 | :samp:`read <uuid> <interface>` | 366 | :samp:`read <uuid> <interface>` |
761 | 356 | 367 | ||
762 | 357 | Returns the current settings for the given UUID and interface | 368 | Returns the current settings for the given UUID and interface |
763 | 358 | 369 | ||
764 | 359 | :samp:`update [parameters]` | 370 | :samp:`update [parameters]` |
766 | 360 | 371 | ||
767 | 361 | Changes the settings for the interface according to the given | 372 | Changes the settings for the interface according to the given |
768 | 362 | parameters:: | 373 | parameters:: |
769 | 363 | 374 | ||
770 | 364 | management= 0 | 1 | 2 | 375 | management= 0 | 1 | 2 |
772 | 365 | The service to be managed on the interface ( 0= none, 1=DHCP, 2=DHCP | 376 | The service to be managed on the interface ( 0= none, 1=DHCP, 2=DHCP |
773 | 366 | and DNS). | 377 | and DNS). |
774 | 367 | 378 | ||
775 | 368 | subnet_mask=<value> | 379 | subnet_mask=<value> |
776 | 369 | Apply the given dotted decimal value as the subnet mask. | 380 | Apply the given dotted decimal value as the subnet mask. |
777 | 370 | 381 | ||
778 | 371 | broadcast_ip=<value> | 382 | broadcast_ip=<value> |
780 | 372 | Apply the given dotted decimal value as the broadcast IP address for | 383 | Apply the given dotted decimal value as the broadcast IP address for |
781 | 373 | this subnet. | 384 | this subnet. |
782 | 374 | 385 | ||
783 | 375 | router_ip=<value> | 386 | router_ip=<value> |
785 | 376 | Apply the given dotted decimal value as the default router address | 387 | Apply the given dotted decimal value as the default router address |
786 | 377 | for this subnet. | 388 | for this subnet. |
787 | 378 | 389 | ||
788 | 379 | ip_range_low=<value> | 390 | ip_range_low=<value> |
789 | 380 | The lowest value of IP address to allocate via DHCP | 391 | The lowest value of IP address to allocate via DHCP |
790 | 381 | 392 | ||
791 | 382 | ip_range_high=<value> | 393 | ip_range_high=<value> |
793 | 383 | The highest value of IP address to allocate via DHCP | 394 | The highest value of IP address to allocate via DHCP |
794 | 384 | 395 | ||
795 | 385 | :samp:`delete <uuid> <interface>` | 396 | :samp:`delete <uuid> <interface>` |
796 | 386 | 397 | ||
797 | 387 | Removes the entry for the given UUID and interface. | 398 | Removes the entry for the given UUID and interface. |
799 | 388 | 399 | ||
800 | 389 | .. _cli-dhcp: | 400 | .. _cli-dhcp: |
801 | 390 | 401 | ||
802 | 391 | Example: | 402 | Example: |
803 | 392 | Configuring DHCP and DNS. | 403 | Configuring DHCP and DNS. |
804 | 393 | 404 | ||
806 | 394 | To enable MAAS to manage DHCP and DNS, it needs to be supplied with the relevant | 405 | To enable MAAS to manage DHCP and DNS, it needs to be supplied with the relevant |
807 | 395 | interface information. To do this we need to first determine the UUID of the | 406 | interface information. To do this we need to first determine the UUID of the |
808 | 396 | node group affected:: | 407 | node group affected:: |
809 | 397 | 408 | ||
810 | 398 | $ uuid=$(maas-cli <profile> node-groups list | grep uuid | cut -d\" -f4) | 409 | $ uuid=$(maas-cli <profile> node-groups list | grep uuid | cut -d\" -f4) |
812 | 399 | 410 | ||
813 | 400 | Once we have the UUID we can use this to update the node-group-interface for | 411 | Once we have the UUID we can use this to update the node-group-interface for |
814 | 401 | that nodegroup, and pass it the relevant interface details:: | 412 | that nodegroup, and pass it the relevant interface details:: |
815 | 402 | 413 | ||
816 | @@ -407,13 +418,12 @@ | |||
817 | 407 | broadcast_ip=192.168.123.255 \ | 418 | broadcast_ip=192.168.123.255 \ |
818 | 408 | router_ip=192.168.123.1 \ | 419 | router_ip=192.168.123.1 \ |
819 | 409 | 420 | ||
823 | 410 | Replacing the example values with those required for this network. The | 421 | Replacing the example values with those required for this network. The only |
824 | 411 | only non-obvious parameter is 'management' which takes the values 0 | 422 | non-obvious parameter is 'management' which takes the values 0 (no management), 1 |
825 | 412 | (no management), 1 (manage DHCP) and 2 (manage DHCP and DNS). | 423 | (manage DHCP) and 2 (manage DHCP and DNS). |
826 | 413 | 424 | ||
827 | 414 | 425 | ||
828 | 415 | .. _node-group-interfaces: | 426 | .. _node-group-interfaces: |
829 | 416 | |||
830 | 417 | node-group-interfaces | 427 | node-group-interfaces |
831 | 418 | ^^^^^^^^^^^^^^^^^^^^^ | 428 | ^^^^^^^^^^^^^^^^^^^^^ |
832 | 419 | 429 | ||
833 | @@ -428,7 +438,7 @@ | |||
834 | 428 | :samp:`-d, --debug` | 438 | :samp:`-d, --debug` |
835 | 429 | 439 | ||
836 | 430 | Displays debug information listing the API responses. | 440 | Displays debug information listing the API responses. |
838 | 431 | 441 | ||
839 | 432 | :samp:`-h, --help` | 442 | :samp:`-h, --help` |
840 | 433 | 443 | ||
841 | 434 | Display usage information. | 444 | Display usage information. |
842 | @@ -442,24 +452,25 @@ | |||
843 | 442 | Lists the current stored configurations for the given identifier | 452 | Lists the current stored configurations for the given identifier |
844 | 443 | <label> in a key:value format which should be easy to decipher. | 453 | <label> in a key:value format which should be easy to decipher. |
845 | 444 | 454 | ||
846 | 455 | |||
847 | 445 | :samp:`new <label> ip=<value> interface=<if_device> [parameters...]` | 456 | :samp:`new <label> ip=<value> interface=<if_device> [parameters...]` |
849 | 446 | 457 | ||
850 | 447 | Creates a new interface group. The required parameters are the IP | 458 | Creates a new interface group. The required parameters are the IP |
851 | 448 | address and the network interface this appies to (e.g. eth0). In | 459 | address and the network interface this appies to (e.g. eth0). In |
852 | 449 | order to do anything useful, further parameters are required:: | 460 | order to do anything useful, further parameters are required:: |
853 | 450 | 461 | ||
855 | 451 | management= 0 | 1 | 2 | 462 | management= 0 | 1 | 2 |
856 | 452 | The service to be managed on the interface | 463 | The service to be managed on the interface |
857 | 453 | ( 0= none, 1=DHCP, 2=DHCP and DNS). | 464 | ( 0= none, 1=DHCP, 2=DHCP and DNS). |
858 | 454 | 465 | ||
859 | 455 | subnet_mask=<value> | 466 | subnet_mask=<value> |
860 | 456 | Apply the given dotted decimal value as the subnet mask. | 467 | Apply the given dotted decimal value as the subnet mask. |
861 | 457 | 468 | ||
863 | 458 | broadcast_ip=<value> | 469 | broadcast_ip=<value> |
864 | 459 | Apply the given dotted decimal value as the | 470 | Apply the given dotted decimal value as the |
865 | 460 | broadcast IP address for this subnet. | 471 | broadcast IP address for this subnet. |
866 | 461 | 472 | ||
868 | 462 | router_ip=<value> | 473 | router_ip=<value> |
869 | 463 | Apply the given dotted decimal value as the | 474 | Apply the given dotted decimal value as the |
870 | 464 | default router address for this subnet. | 475 | default router address for this subnet. |
871 | 465 | 476 | ||
872 | @@ -470,16 +481,18 @@ | |||
873 | 470 | The highest value of IP address to allocate via DHCP | 481 | The highest value of IP address to allocate via DHCP |
874 | 471 | 482 | ||
875 | 472 | 483 | ||
877 | 473 | tag | 484 | |
878 | 485 | |||
879 | 486 | tag | ||
880 | 474 | ^^^ | 487 | ^^^ |
881 | 475 | 488 | ||
882 | 476 | Usage: maas-cli <profile> tag read | update-nodes | rebuild | update | | 489 | Usage: maas-cli <profile> tag read | update-nodes | rebuild | update | |
884 | 477 | nodes | delete | 490 | nodes | delete |
885 | 478 | 491 | ||
886 | 479 | .. program:: maas-cli tag | 492 | .. program:: maas-cli tag |
887 | 480 | 493 | ||
888 | 481 | :samp:`read <tag_name>` | 494 | :samp:`read <tag_name>` |
890 | 482 | 495 | ||
891 | 483 | Returns information on the tag specified by <name> | 496 | Returns information on the tag specified by <name> |
892 | 484 | 497 | ||
893 | 485 | :samp:`update-nodes <tag_name> [add=<system_id>] [remove=<system_id>] [nodegroup=<system_id>]` | 498 | :samp:`update-nodes <tag_name> [add=<system_id>] [remove=<system_id>] [nodegroup=<system_id>]` |
894 | @@ -492,10 +505,10 @@ | |||
895 | 492 | 505 | ||
896 | 493 | :samp:`rebuild` | 506 | :samp:`rebuild` |
897 | 494 | 507 | ||
899 | 495 | Triggers a rebuild of the tag to node mapping. | 508 | Triggers a rebuild of the tag to node mapping. |
900 | 496 | 509 | ||
901 | 497 | :samp:`update <tag_name> [name=<value>] | [comment=<value>]|[definition=<value>]` | 510 | :samp:`update <tag_name> [name=<value>] | [comment=<value>]|[definition=<value>]` |
903 | 498 | 511 | ||
904 | 499 | Updates the tag identified by tag_name. Any or all of name,comment | 512 | Updates the tag identified by tag_name. Any or all of name,comment |
905 | 500 | and definition may be supplied as parameters. If no parameters are | 513 | and definition may be supplied as parameters. If no parameters are |
906 | 501 | supplied, this command returns the current values. | 514 | supplied, this command returns the current values. |
907 | @@ -508,17 +521,12 @@ | |||
908 | 508 | 521 | ||
909 | 509 | Deletes the given tag. | 522 | Deletes the given tag. |
910 | 510 | 523 | ||
922 | 511 | 524 | tags | |
923 | 512 | tags | 525 | ^^^^ |
924 | 513 | ^^^^ | 526 | Tags are a really useful way of identifying nodes with particular |
925 | 514 | 527 | characteristics. | |
926 | 515 | Tags are a really useful way of identifying nodes with particular | 528 | |
927 | 516 | characteristics. | 529 | .. only:: html For more information on how to use them effectively, please see :ref:`deploy-tags` |
917 | 517 | |||
918 | 518 | .. only:: html | ||
919 | 519 | |||
920 | 520 | For more information on how to use them effectively, please see | ||
921 | 521 | :ref:`deploy-tags` | ||
928 | 522 | 530 | ||
929 | 523 | Usage: maas-cli <profile> tag [-d --debug] [-h --help] [-k | 531 | Usage: maas-cli <profile> tag [-d --debug] [-h --help] [-k |
930 | 524 | --insecure] list | new | 532 | --insecure] list | new |
931 | @@ -528,38 +536,39 @@ | |||
932 | 528 | :samp:`-d, --debug` | 536 | :samp:`-d, --debug` |
933 | 529 | 537 | ||
934 | 530 | Displays debug information listing the API responses. | 538 | Displays debug information listing the API responses. |
936 | 531 | 539 | ||
937 | 532 | :samp:`-h, --help` | 540 | :samp:`-h, --help` |
938 | 533 | 541 | ||
939 | 534 | Display usage information. | 542 | Display usage information. |
940 | 535 | 543 | ||
942 | 536 | :samp:`-k, --insecure` | 544 | :samp:`-k, --insecure` |
943 | 537 | 545 | ||
944 | 538 | Disables the SSL certificate check. | 546 | Disables the SSL certificate check. |
945 | 539 | 547 | ||
946 | 540 | :samp:`list` | 548 | :samp:`list` |
948 | 541 | 549 | ||
949 | 542 | Returns a JSON object listing all the current tags known by the MAAS server | 550 | Returns a JSON object listing all the current tags known by the MAAS server |
950 | 543 | 551 | ||
951 | 544 | :samp:`create name=<value> definition=<value> [comment=<value>]` | 552 | :samp:`create name=<value> definition=<value> [comment=<value>]` |
952 | 545 | 553 | ||
953 | 546 | Creates a new tag with the given name and definition. A comment is | 554 | Creates a new tag with the given name and definition. A comment is |
954 | 547 | optional. Names must be unique, obviously - an error will be | 555 | optional. Names must be unique, obviously - an error will be |
959 | 548 | returned if the given name already exists. The definition is in the | 556 | returned if the given name already exists. The definition is in the form of |
960 | 549 | form of an XPath expression which parses the XML returned by | 557 | an XPath expression which parses the XML returned by running ``lshw`` on the |
961 | 550 | running ``lshw`` on the node. | 558 | node. |
962 | 551 | 559 | ||
963 | 552 | Example: | 560 | Example: |
964 | 553 | Adding a tag to all nodes which have an Intel GPU:: | 561 | Adding a tag to all nodes which have an Intel GPU:: |
965 | 554 | 562 | ||
966 | 555 | $ maas-cli maas tags new name='intel-gpu' \ | 563 | $ maas-cli maas tags new name='intel-gpu' \ |
967 | 556 | comment='Machines which have an Intel display driver' \ | 564 | comment='Machines which have an Intel display driver' \ |
968 | 557 | definition='contains(//node[@id="display"]/vendor, "Intel") | 565 | definition='contains(//node[@id="display"]/vendor, "Intel") |
974 | 558 | 566 | ||
975 | 559 | 567 | ||
976 | 560 | unused commands | 568 | unused commands |
977 | 561 | ^^^^^^^^^^^^^^^ | 569 | ^^^^^^^^^^^^^^^ |
973 | 562 | |||
978 | 563 | Because the ``maas-cli`` command exposes all of the API, it also lists | 570 | Because the ``maas-cli`` command exposes all of the API, it also lists |
979 | 564 | some command options which are not really intended for end users, such | 571 | some command options which are not really intended for end users, such |
980 | 565 | as the "file" and "boot-images" options. | 572 | as the "file" and "boot-images" options. |
981 | 573 | |||
982 | 574 | |||
983 | 566 | 575 | ||
984 | === modified file 'docs/man/maas-cli.8.rst' | |||
985 | --- docs/man/maas-cli.8.rst 2012-11-20 21:46:37 +0000 | |||
986 | +++ docs/man/maas-cli.8.rst 2012-11-23 13:00:36 +0000 | |||
987 | @@ -1,29 +1,564 @@ | |||
988 | 1 | |||
989 | 1 | maas-cli | 2 | maas-cli |
990 | 2 | -------- | 3 | -------- |
991 | 3 | 4 | ||
992 | 4 | |||
993 | 5 | Usage | 5 | Usage |
994 | 6 | ^^^^^ | 6 | ^^^^^ |
995 | 7 | 7 | ||
996 | 8 | $ maas-cli <profile> <command> [parameters] | 8 | $ maas-cli <profile> <command> [parameters] |
998 | 9 | 9 | ||
999 | 10 | The available commands are dependent on the API you are connecting to and the | 10 | The available commands are dependent on the API you are connecting to and the |
1001 | 11 | profile you use. The currently available options are explained below. | 11 | profile you use. The currently available options are explained below. |
1002 | 12 | 12 | ||
1003 | 13 | 13 | ||
1004 | 14 | Description | 14 | Description |
1005 | 15 | ^^^^^^^^^^^ | 15 | ^^^^^^^^^^^ |
1006 | 16 | 16 | ||
1009 | 17 | .. include:: ../maascli.rst | 17 | As well as the web interface, many tasks can be performed by accessing |
1010 | 18 | 18 | the MAAS API directly through the maas-cli command. This section | |
1011 | 19 | details how to login with this tool and perform some common | ||
1012 | 20 | operations. | ||
1013 | 21 | |||
1014 | 22 | |||
1015 | 23 | Logging in | ||
1016 | 24 | ---------- | ||
1017 | 25 | |||
1018 | 26 | Before the API will accept any commands from maas-cli, you must first | ||
1019 | 27 | login. To do this, you need the API key which can be found in the user | ||
1020 | 28 | interface. | ||
1021 | 29 | |||
1022 | 30 | Login to the web interface on your MAAS. Click on the username in the | ||
1023 | 31 | top right corner and select 'Preferences' from the menu which appears. | ||
1024 | 32 | |||
1025 | 33 | The very first item is a list of MAAS keys. One will have already been | ||
1026 | 34 | generated when the system was installed. It's easiest to just select | ||
1027 | 35 | and copy the key (it's quite long!) and then paste it into the | ||
1028 | 36 | commandline. The format of the login command is:: | ||
1029 | 37 | |||
1030 | 38 | $ maas-cli login <profile-name> <hostname> <key> | ||
1031 | 39 | |||
1032 | 40 | The profile created is an easy way of associating your credentials with any | ||
1033 | 41 | subsequent call to the API. So an example login might look like this:: | ||
1034 | 42 | |||
1035 | 43 | $ maas-cli login maas http://10.98.0.13/MAAS/api/1.0 AWSCRMzqMNy:jjk...5e1FenoP82Qm5te2 | ||
1036 | 44 | |||
1037 | 45 | which creates the profile 'maas' and registers it with the given key at the | ||
1038 | 46 | specified API endpoint. | ||
1039 | 47 | If you omit the credentials, they will be prompted for in the console. It is | ||
1040 | 48 | also possible to use a hyphen, '-' in place of the credentials. In this case a | ||
1041 | 49 | single line will be read from stdin, stripped of any whitespace and used as the | ||
1042 | 50 | credentials, which can be useful if you are devolping scripts for specific | ||
1043 | 51 | tasks. | ||
1044 | 52 | If an empty string is passed instead of the credentials, the profile will be | ||
1045 | 53 | logged in anonymously (and consequently some of the API calls will not be | ||
1046 | 54 | available) | ||
1047 | 55 | |||
1048 | 56 | |||
1049 | 57 | maas-cli commands | ||
1050 | 58 | ----------------- | ||
1051 | 59 | |||
1052 | 60 | The ``maas-cli`` command exposes the whole API, so you can do anything | ||
1053 | 61 | you actually *can* do with MAAS using this command. Unsurprisingly, | ||
1054 | 62 | this leaves us with a vast number of options. | ||
1055 | 63 | |||
1056 | 64 | The main maas-cli commands are: | ||
1057 | 65 | |||
1058 | 66 | .. program:: maas-cli | ||
1059 | 67 | |||
1060 | 68 | :samp:`list` | ||
1061 | 69 | |||
1062 | 70 | lists the details [name url auth-key] of all the currently logged-in | ||
1063 | 71 | profiles. | ||
1064 | 72 | |||
1065 | 73 | :samp:`login <profile> <url> <key>` | ||
1066 | 74 | |||
1067 | 75 | Logs in to the MAAS controller API at the given URL, using the key | ||
1068 | 76 | provided and associates this connection with the given profile name. | ||
1069 | 77 | |||
1070 | 78 | :samp:`logout <profile>` | ||
1071 | 79 | |||
1072 | 80 | Logs out from the given profile, flushing the stored credentials. | ||
1073 | 81 | |||
1074 | 82 | :samp:`refresh` | ||
1075 | 83 | |||
1076 | 84 | Refreshes the API descriptions of all the current logged in | ||
1077 | 85 | profiles. This may become necessary for example when upgrading the | ||
1078 | 86 | maas packages to ensure the command-line options match with the API. | ||
1079 | 87 | |||
1080 | 88 | :samp:`<profile> [command] [options] ...` | ||
1081 | 89 | |||
1082 | 90 | Using the given profile name instructs ``maas-cli`` to direct the | ||
1083 | 91 | subsequent commands and options to the relevant MAAS, which for the | ||
1084 | 92 | current API are detailed below... | ||
1085 | 93 | |||
1086 | 94 | |||
1087 | 95 | account | ||
1088 | 96 | ^^^^^^^ | ||
1089 | 97 | This command is used for creating and destroying the | ||
1090 | 98 | MAAS authorisation tokens associated with a profile. | ||
1091 | 99 | |||
1092 | 100 | Usage: maas-cli *<profile>* account [-d --debug] [-h --help] | ||
1093 | 101 | create-authorisation-token | delete-authorisation-token [token_key=\ | ||
1094 | 102 | *<value>*] | ||
1095 | 103 | |||
1096 | 104 | .. program:: maas-cli account | ||
1097 | 105 | |||
1098 | 106 | :samp:`-d, --debug` | ||
1099 | 107 | |||
1100 | 108 | Displays debug information listing the API responses. | ||
1101 | 109 | |||
1102 | 110 | :samp:`-h, --help` | ||
1103 | 111 | |||
1104 | 112 | Display usage information. | ||
1105 | 113 | |||
1106 | 114 | :samp:`-k, --insecure` | ||
1107 | 115 | |||
1108 | 116 | Disables the SSL certificate check. | ||
1109 | 117 | |||
1110 | 118 | :samp:`create-authorisation-token` | ||
1111 | 119 | |||
1112 | 120 | Creates a new MAAS authorisation token for the current profile | ||
1113 | 121 | which can be used to authenticate connections to the API. | ||
1114 | 122 | |||
1115 | 123 | :samp:`delete-authorisation-token token_key=<value>` | ||
1116 | 124 | |||
1117 | 125 | Removes the given key from the list of authorisation tokens. | ||
1118 | 126 | |||
1119 | 127 | |||
1120 | 128 | node | ||
1121 | 129 | ^^^^ | ||
1122 | 130 | |||
1123 | 131 | API calls which operate on individual nodes. With these commands, the | ||
1124 | 132 | node is always identified by its "system_id" property - a unique tag | ||
1125 | 133 | allocated at the time of enlistment. To discover the value of the | ||
1126 | 134 | system_id, you can use the ``maas-cli <profile> nodes list`` command. | ||
1127 | 135 | |||
1128 | 136 | USAGE: maas-cli <profile> node [-h] release | start | stop | delete | | ||
1129 | 137 | read | update <system_id> | ||
1130 | 138 | |||
1131 | 139 | .. program:: maas-cli node | ||
1132 | 140 | |||
1133 | 141 | :samp:`-h, --help` | ||
1134 | 142 | |||
1135 | 143 | Display usage information. | ||
1136 | 144 | |||
1137 | 145 | :samp:`release <system_id>` | ||
1138 | 146 | |||
1139 | 147 | Releases the node given by *<system_id>* | ||
1140 | 148 | |||
1141 | 149 | :samp:`start <system_id>` | ||
1142 | 150 | |||
1143 | 151 | Powers up the node identified by *<system_id>* (where MAAS has | ||
1144 | 152 | information for power management for this node). | ||
1145 | 153 | |||
1146 | 154 | :samp:`stop <system_id>` | ||
1147 | 155 | |||
1148 | 156 | Powers off the node identified by *<system_id>* (where MAAS has | ||
1149 | 157 | information for power management for this node). | ||
1150 | 158 | |||
1151 | 159 | :samp:`delete <system_id>` | ||
1152 | 160 | |||
1153 | 161 | Removes the given node from the MAAS database. | ||
1154 | 162 | |||
1155 | 163 | :samp:`read <system_id>` | ||
1156 | 164 | |||
1157 | 165 | Returns all the current known information about the node specified | ||
1158 | 166 | by *<system_id>* | ||
1159 | 167 | |||
1160 | 168 | :samp:`update <system_id> [parameters...]` | ||
1161 | 169 | |||
1162 | 170 | Used to change or set specific values for the node. The valid | ||
1163 | 171 | parameters are listed below:: | ||
1164 | 172 | |||
1165 | 173 | hostname=<value> | ||
1166 | 174 | The new hostname for this node. | ||
1167 | 175 | |||
1168 | 176 | architecture=<value> | ||
1169 | 177 | Sets the architecture type, where <value> | ||
1170 | 178 | is a string containing a valid architecture type, | ||
1171 | 179 | e.g. "i386/generic" | ||
1172 | 180 | |||
1173 | 181 | distro_series=<value> | ||
1174 | 182 | Sets the series of Ubuntu to use. | ||
1175 | 183 | |||
1176 | 184 | power_type=<value> | ||
1177 | 185 | Sets the type of power management used on the node, e.g. "ipmi" or | ||
1178 | 186 | "virsh". | ||
1179 | 187 | |||
1180 | 188 | power_parameters_{param1}... =<value> | ||
1181 | 189 | Set the given power parameters. Note that the valid options for these | ||
1182 | 190 | depend on the power type chosen. | ||
1183 | 191 | |||
1184 | 192 | power_parameters_skip_check 'true' | 'false' | ||
1185 | 193 | Whether to sanity check the supplied parameters against this node's | ||
1186 | 194 | declared power type. The default is 'false'. | ||
1187 | 195 | |||
1188 | 196 | |||
1189 | 197 | |||
1190 | 198 | .. _cli-power: | ||
1191 | 199 | |||
1192 | 200 | Example: Setting the power parameters for an ipmi enabled node:: | ||
1193 | 201 | |||
1194 | 202 | maas-cli maas node update <system_id> \ | ||
1195 | 203 | power_type="ipmi" \ | ||
1196 | 204 | power_parameters_power_address=192.168.22.33 \ | ||
1197 | 205 | power_parameters_power_user=root \ | ||
1198 | 206 | power_parameters_power_pass=ubuntu; | ||
1199 | 207 | |||
1200 | 208 | |||
1201 | 209 | |||
1202 | 210 | |||
1203 | 211 | nodes | ||
1204 | 212 | ^^^^^ | ||
1205 | 213 | |||
1206 | 214 | Usage: maas-cli <profile> nodes [-h] is-registered | list-allocated | | ||
1207 | 215 | acquire | list | accept | accept-all | new | check-commissioning | ||
1208 | 216 | |||
1209 | 217 | .. program:: maas-cli nodes | ||
1210 | 218 | |||
1211 | 219 | :samp:`-h, --help` | ||
1212 | 220 | |||
1213 | 221 | Display usage information. | ||
1214 | 222 | |||
1215 | 223 | |||
1216 | 224 | :samp:`accept <system_id>` | ||
1217 | 225 | |||
1218 | 226 | Accepts the node referenced by <system_id>. | ||
1219 | 227 | |||
1220 | 228 | :samp:`accept-all` | ||
1221 | 229 | |||
1222 | 230 | Accepts all currently discovered but not previously accepted nodes. | ||
1223 | 231 | |||
1224 | 232 | :samp:`acquire` | ||
1225 | 233 | |||
1226 | 234 | Allocates a node to the profile used to issue the command. Any | ||
1227 | 235 | ready node may be allocated. | ||
1228 | 236 | |||
1229 | 237 | :samp:`is-registered mac_address=<address>` | ||
1230 | 238 | |||
1231 | 239 | Checks to see whether the specified MAC address is registered to a | ||
1232 | 240 | node. | ||
1233 | 241 | |||
1234 | 242 | :samp:`list` | ||
1235 | 243 | |||
1236 | 244 | Returns a JSON formatted object listing all the currently known | ||
1237 | 245 | nodes, their system_id, status and other details. | ||
1238 | 246 | |||
1239 | 247 | :samp:`list-allocated` | ||
1240 | 248 | |||
1241 | 249 | Returns a JSON formatted object listing all the currently allocated | ||
1242 | 250 | nodes, their system_id, status and other details. | ||
1243 | 251 | |||
1244 | 252 | :samp:`new architecture=<value> mac_addresses=<value> [parameters]` | ||
1245 | 253 | |||
1246 | 254 | Creates a new node entry given the provided key=value information | ||
1247 | 255 | for the node. A minimum of the MAC address and architecture must be | ||
1248 | 256 | provided. Other parameters may also be supplied:: | ||
1249 | 257 | |||
1250 | 258 | architecture="<value>" - The architecture of the node, must be | ||
1251 | 259 | one of the recognised architecture strings (e.g. "i386/generic") | ||
1252 | 260 | hostname="<value>" - a name for this node. If not supplied a name | ||
1253 | 261 | will be generated. | ||
1254 | 262 | mac_addresses="<value>" - The mac address(es) | ||
1255 | 263 | allocated to this node. | ||
1256 | 264 | powertype="<value>" - the power type of | ||
1257 | 265 | the node (e.g. virsh, ipmi) | ||
1258 | 266 | |||
1259 | 267 | |||
1260 | 268 | :samp:`check-commissioning` | ||
1261 | 269 | |||
1262 | 270 | Displays current status of nodes in the commissioning phase. Any | ||
1263 | 271 | that have not returned before the system timeout value are listed | ||
1264 | 272 | as "failed". | ||
1265 | 273 | |||
1266 | 274 | Examples: | ||
1267 | 275 | Accept and commission all discovered nodes:: | ||
1268 | 276 | |||
1269 | 277 | $ maas-cli maas nodes accept-all | ||
1270 | 278 | |||
1271 | 279 | List all known nodes:: | ||
1272 | 280 | |||
1273 | 281 | $ maas-cli maas nodes list | ||
1274 | 282 | |||
1275 | 283 | Filter the list using specific key/value pairs:: | ||
1276 | 284 | |||
1277 | 285 | $ maas-cli maas nodes list architecture="i386/generic" | ||
1278 | 286 | |||
1279 | 287 | |||
1280 | 288 | |||
1281 | 289 | node-groups | ||
1282 | 290 | ^^^^^^^^^^^ | ||
1283 | 291 | Usage: maas-cli <profile> node-groups [-d --debug] [-h --help] [-k | ||
1284 | 292 | --insecure] register | list | refresh-workers | accept | reject | ||
1285 | 293 | |||
1286 | 294 | .. program:: maas-cli node-groups | ||
1287 | 295 | |||
1288 | 296 | :samp:`-d, --debug` | ||
1289 | 297 | |||
1290 | 298 | Displays debug information listing the API responses. | ||
1291 | 299 | |||
1292 | 300 | :samp:`-h, --help` | ||
1293 | 301 | |||
1294 | 302 | Display usage information. | ||
1295 | 303 | |||
1296 | 304 | :samp:`-k, --insecure` | ||
1297 | 305 | |||
1298 | 306 | Disables the SSL certificate check. | ||
1299 | 307 | |||
1300 | 308 | :samp:`register uuid=<value> name=<value> interfaces=<json_string>` | ||
1301 | 309 | |||
1302 | 310 | Registers a new node group with the given name and uuid. The | ||
1303 | 311 | interfaces parameter must be supplied in the form of a JSON string | ||
1304 | 312 | comprising the key/value data for the interface to be used, for | ||
1305 | 313 | example: interface='["ip":"192.168.21.5","interface":"eth1", \ | ||
1306 | 314 | "subnet_mask":"255.255.255.0","broadcast_ip":"192.168.21.255", \ | ||
1307 | 315 | "router_ip":"192.168.21.1", "ip_range_low":"192.168.21.10", \ | ||
1308 | 316 | "ip_range_high":"192.168.21.50"}]' | ||
1309 | 317 | |||
1310 | 318 | :samp:`list` | ||
1311 | 319 | |||
1312 | 320 | Returns a JSON list of all currently defined node groups. | ||
1313 | 321 | |||
1314 | 322 | :samp:`refresh_workers` | ||
1315 | 323 | |||
1316 | 324 | It sounds a bit like they will get a cup of tea and a | ||
1317 | 325 | biscuit. Actually this just sends each node-group worker an update | ||
1318 | 326 | of its credentials (API key, node-group name). This command is | ||
1319 | 327 | usually not needed at a user level, but is often used by worker | ||
1320 | 328 | nodes. | ||
1321 | 329 | |||
1322 | 330 | :samp:`accept <uuid>` | ||
1323 | 331 | |||
1324 | 332 | Accepts a node-group or number of nodegroups indicated by the | ||
1325 | 333 | supplied UUID | ||
1326 | 334 | |||
1327 | 335 | :samp:`reject <uuid>` | ||
1328 | 336 | |||
1329 | 337 | Rejects a node-group or number of nodegroups indicated by the | ||
1330 | 338 | supplied UUID | ||
1331 | 339 | |||
1332 | 340 | |||
1333 | 341 | |||
1334 | 342 | node-group-interface | ||
1335 | 343 | ^^^^^^^^^^^^^^^^^^^^ | ||
1336 | 344 | For managing the interfaces. See also | ||
1337 | 345 | "node_group_interfaces" | ||
1338 | 346 | |||
1339 | 347 | Usage: maas-cli *<profile>* node-group-interface [-d --debug] [-h | ||
1340 | 348 | --help] [-k --insecure] read | update | delete [parameters...] | ||
1341 | 349 | |||
1342 | 350 | ..program:: maas-cli node-group-interface | ||
1343 | 351 | |||
1344 | 352 | :samp:`read <uuid> <interface>` | ||
1345 | 353 | |||
1346 | 354 | Returns the current settings for the given UUID and interface | ||
1347 | 355 | |||
1348 | 356 | :samp:`update [parameters]` | ||
1349 | 357 | |||
1350 | 358 | Changes the settings for the interface according to the given | ||
1351 | 359 | parameters:: | ||
1352 | 360 | |||
1353 | 361 | management= 0 | 1 | 2 | ||
1354 | 362 | The service to be managed on the interface ( 0= none, 1=DHCP, 2=DHCP | ||
1355 | 363 | and DNS). | ||
1356 | 364 | |||
1357 | 365 | subnet_mask=<value> | ||
1358 | 366 | Apply the given dotted decimal value as the subnet mask. | ||
1359 | 367 | |||
1360 | 368 | broadcast_ip=<value> | ||
1361 | 369 | Apply the given dotted decimal value as the broadcast IP address for | ||
1362 | 370 | this subnet. | ||
1363 | 371 | |||
1364 | 372 | router_ip=<value> | ||
1365 | 373 | Apply the given dotted decimal value as the default router address | ||
1366 | 374 | for this subnet. | ||
1367 | 375 | |||
1368 | 376 | ip_range_low=<value> | ||
1369 | 377 | The lowest value of IP address to allocate via DHCP | ||
1370 | 378 | |||
1371 | 379 | ip_range_high=<value> | ||
1372 | 380 | The highest value of IP address to allocate via DHCP | ||
1373 | 381 | |||
1374 | 382 | :samp:`delete <uuid> <interface>` | ||
1375 | 383 | |||
1376 | 384 | Removes the entry for the given UUID and interface. | ||
1377 | 385 | |||
1378 | 386 | |||
1379 | 387 | Example: | ||
1380 | 388 | Configuring DHCP and DNS. | ||
1381 | 389 | |||
1382 | 390 | To enable MAAS to manage DHCP and DNS, it needs to be supplied with the relevant | ||
1383 | 391 | interface information. To do this we need to first determine the UUID of the | ||
1384 | 392 | node group affected:: | ||
1385 | 393 | |||
1386 | 394 | $ uuid=$(maas-cli <profile> node-groups list | grep uuid | cut -d\" -f4) | ||
1387 | 395 | |||
1388 | 396 | Once we have the UUID we can use this to update the node-group-interface for | ||
1389 | 397 | that nodegroup, and pass it the relevant interface details:: | ||
1390 | 398 | |||
1391 | 399 | $ maas-cli <profile> node-group-interface update $uuid eth0 \ | ||
1392 | 400 | ip_range_high=192.168.123.200 \ | ||
1393 | 401 | ip_range_low=192.168.123.100 \ | ||
1394 | 402 | management=2 \ | ||
1395 | 403 | broadcast_ip=192.168.123.255 \ | ||
1396 | 404 | router_ip=192.168.123.1 \ | ||
1397 | 405 | |||
1398 | 406 | Replacing the example values with those required for this network. The only | ||
1399 | 407 | non-obvious parameter is 'management' which takes the values 0 (no management), 1 | ||
1400 | 408 | (manage DHCP) and 2 (manage DHCP and DNS). | ||
1401 | 409 | |||
1402 | 410 | |||
1403 | 411 | node-group-interfaces | ||
1404 | 412 | ^^^^^^^^^^^^^^^^^^^^^ | ||
1405 | 413 | |||
1406 | 414 | The node-group-interfaces commands are used for configuring the | ||
1407 | 415 | management of DHCP and DNS services where these are managed by MAAS. | ||
1408 | 416 | |||
1409 | 417 | Usage: maas-cli *<profile>* node-group-interfaces [-d --debug] [-h | ||
1410 | 418 | --help] [-k --insecure] list | new [parameters...] | ||
1411 | 419 | |||
1412 | 420 | .. program:: maas-cli node-group-interfaces | ||
1413 | 421 | |||
1414 | 422 | :samp:`-d, --debug` | ||
1415 | 423 | |||
1416 | 424 | Displays debug information listing the API responses. | ||
1417 | 425 | |||
1418 | 426 | :samp:`-h, --help` | ||
1419 | 427 | |||
1420 | 428 | Display usage information. | ||
1421 | 429 | |||
1422 | 430 | :samp:`-k, --insecure` | ||
1423 | 431 | |||
1424 | 432 | Disables the SSL certificate check. | ||
1425 | 433 | |||
1426 | 434 | :samp:`list <label>` | ||
1427 | 435 | |||
1428 | 436 | Lists the current stored configurations for the given identifier | ||
1429 | 437 | <label> in a key:value format which should be easy to decipher. | ||
1430 | 438 | |||
1431 | 439 | |||
1432 | 440 | :samp:`new <label> ip=<value> interface=<if_device> [parameters...]` | ||
1433 | 441 | |||
1434 | 442 | Creates a new interface group. The required parameters are the IP | ||
1435 | 443 | address and the network interface this appies to (e.g. eth0). In | ||
1436 | 444 | order to do anything useful, further parameters are required:: | ||
1437 | 445 | |||
1438 | 446 | management= 0 | 1 | 2 | ||
1439 | 447 | The service to be managed on the interface | ||
1440 | 448 | ( 0= none, 1=DHCP, 2=DHCP and DNS). | ||
1441 | 449 | |||
1442 | 450 | subnet_mask=<value> | ||
1443 | 451 | Apply the given dotted decimal value as the subnet mask. | ||
1444 | 452 | |||
1445 | 453 | broadcast_ip=<value> | ||
1446 | 454 | Apply the given dotted decimal value as the | ||
1447 | 455 | broadcast IP address for this subnet. | ||
1448 | 456 | |||
1449 | 457 | router_ip=<value> | ||
1450 | 458 | Apply the given dotted decimal value as the | ||
1451 | 459 | default router address for this subnet. | ||
1452 | 460 | |||
1453 | 461 | ip_range_low=<value> | ||
1454 | 462 | The lowest value of IP address to allocate via DHCP | ||
1455 | 463 | |||
1456 | 464 | ip_range_high=<value> | ||
1457 | 465 | The highest value of IP address to allocate via DHCP | ||
1458 | 466 | |||
1459 | 467 | |||
1460 | 468 | |||
1461 | 469 | |||
1462 | 470 | tag | ||
1463 | 471 | ^^^ | ||
1464 | 472 | |||
1465 | 473 | Usage: maas-cli <profile> tag read | update-nodes | rebuild | update | | ||
1466 | 474 | nodes | delete | ||
1467 | 475 | |||
1468 | 476 | .. program:: maas-cli tag | ||
1469 | 477 | |||
1470 | 478 | :samp:`read <tag_name>` | ||
1471 | 479 | |||
1472 | 480 | Returns information on the tag specified by <name> | ||
1473 | 481 | |||
1474 | 482 | :samp:`update-nodes <tag_name> [add=<system_id>] [remove=<system_id>] [nodegroup=<system_id>]` | ||
1475 | 483 | |||
1476 | 484 | Applies or removes the given tag from a list of nodes specified by | ||
1477 | 485 | either or both of add="<system_id>" and remove="<system_id>". The | ||
1478 | 486 | nodegroup parameter, which restricts the operations to a particular | ||
1479 | 487 | nodegroup, is optional, but only the superuser can execute this | ||
1480 | 488 | command without it. | ||
1481 | 489 | |||
1482 | 490 | :samp:`rebuild` | ||
1483 | 491 | |||
1484 | 492 | Triggers a rebuild of the tag to node mapping. | ||
1485 | 493 | |||
1486 | 494 | :samp:`update <tag_name> [name=<value>] | [comment=<value>]|[definition=<value>]` | ||
1487 | 495 | |||
1488 | 496 | Updates the tag identified by tag_name. Any or all of name,comment | ||
1489 | 497 | and definition may be supplied as parameters. If no parameters are | ||
1490 | 498 | supplied, this command returns the current values. | ||
1491 | 499 | |||
1492 | 500 | :samp:`nodes <tag_name>` | ||
1493 | 501 | |||
1494 | 502 | Returns a list of nodes which are associated with the given tag. | ||
1495 | 503 | |||
1496 | 504 | :samp:`delete <tag_name>` | ||
1497 | 505 | |||
1498 | 506 | Deletes the given tag. | ||
1499 | 507 | |||
1500 | 508 | tags | ||
1501 | 509 | ^^^^ | ||
1502 | 510 | Tags are a really useful way of identifying nodes with particular | ||
1503 | 511 | characteristics. | ||
1504 | 512 | |||
1505 | 513 | Usage: maas-cli <profile> tag [-d --debug] [-h --help] [-k | ||
1506 | 514 | --insecure] list | new | ||
1507 | 515 | |||
1508 | 516 | .. program:: maas-cli tag | ||
1509 | 517 | |||
1510 | 518 | :samp:`-d, --debug` | ||
1511 | 519 | |||
1512 | 520 | Displays debug information listing the API responses. | ||
1513 | 521 | |||
1514 | 522 | :samp:`-h, --help` | ||
1515 | 523 | |||
1516 | 524 | Display usage information. | ||
1517 | 525 | |||
1518 | 526 | :samp:`-k, --insecure` | ||
1519 | 527 | |||
1520 | 528 | Disables the SSL certificate check. | ||
1521 | 529 | |||
1522 | 530 | :samp:`list` | ||
1523 | 531 | |||
1524 | 532 | Returns a JSON object listing all the current tags known by the MAAS server | ||
1525 | 533 | |||
1526 | 534 | :samp:`create name=<value> definition=<value> [comment=<value>]` | ||
1527 | 535 | |||
1528 | 536 | Creates a new tag with the given name and definition. A comment is | ||
1529 | 537 | optional. Names must be unique, obviously - an error will be | ||
1530 | 538 | returned if the given name already exists. The definition is in the form of | ||
1531 | 539 | an XPath expression which parses the XML returned by running ``lshw`` on the | ||
1532 | 540 | node. | ||
1533 | 541 | |||
1534 | 542 | Example: | ||
1535 | 543 | Adding a tag to all nodes which have an Intel GPU:: | ||
1536 | 544 | |||
1537 | 545 | $ maas-cli maas tags new name='intel-gpu' \ | ||
1538 | 546 | comment='Machines which have an Intel display driver' \ | ||
1539 | 547 | definition='contains(//node[@id="display"]/vendor, "Intel") | ||
1540 | 548 | |||
1541 | 549 | |||
1542 | 550 | unused commands | ||
1543 | 551 | ^^^^^^^^^^^^^^^ | ||
1544 | 552 | Because the ``maas-cli`` command exposes all of the API, it also lists | ||
1545 | 553 | some command options which are not really intended for end users, such | ||
1546 | 554 | as the "file" and "boot-images" options. | ||
1547 | 19 | 555 | ||
1548 | 20 | Further Documentation | 556 | Further Documentation |
1549 | 21 | ^^^^^^^^^^^^^^^^^^^^^ | 557 | ^^^^^^^^^^^^^^^^^^^^^ |
1550 | 22 | |||
1551 | 23 | For more documentation of MAAS, please see https://maas.ubuntu.com/docs | 558 | For more documentation of MAAS, please see https://maas.ubuntu.com/docs |
1552 | 24 | 559 | ||
1553 | 25 | |||
1554 | 26 | See Also | 560 | See Also |
1555 | 27 | ^^^^^^^^ | 561 | ^^^^^^^^ |
1556 | 28 | |||
1557 | 29 | `maas` | 562 | `maas` |
1558 | 563 | |||
1559 | 564 |