~hardware-certification/maas-cert-server/trunk : revision 39.1.1

1

=============================================================

2

MAAS Advanced NUC Installation and Configuration -- Scripted

3

=============================================================

4

-----------------------

5

(The MANIACS Document)

6

-----------------------

7

8

.. include:: <isonum.txt>

9

10

.. header:: |ubuntu_logo|

11

12

.. |ubuntu_logo| image:: images/logo-ubuntu_su-white_orange-hex.png

13

:scale: 20%

14

15

.. footer:: |canonical_logo|

16

17

.. |canonical_logo| image:: images/logo-canonical_no-tm-white-hex.png

18

:scale: 10%

19

20

.. raw:: pdf

21

22

PageBreak oneColumn

23

24

.. contents::

25

26

.. raw:: pdf

27

28

PageBreak

29

30

Purpose

31

=======

32

33

This document describes how to install MAAS on a portable computer (such as

34

an Intel NUC or laptop) so that you can deploy systems in a test

35

environment as well as install the certification tools and perform

36

certification testing. Consult the Ubuntu Certified Hardware Self-Testing

37

Guide (available from https://certification.canonical.com) for detailed

38

information on running the certification tests themselves.

39

40

Note that this document is based on using the Ubuntu Desktop image for

41

ease of use, and thus some bits, the Network Manager bits especially,

42

may not apply if you're using Server without a desktop.

43

44

A device (referred to generically as a "portable computer") configured

45

as described here is not intended for general Internet use. Some

46

settings relax security in the interest of ease of use, so you should

47

limit use of the portable computer on the Internet at large.

48

49

This document begins with information on the required hardware and then

50

moves on to details about Ubuntu's network configuration and then the

51

procedures for installing MAAS. (This document assumes that you know how

52

to install Ubuntu.) Because the purpose of this document is to help you

53

bring up a MAAS server for certification purposes, it then describes how

54

to install additional software and configure MAAS to automatically

55

install the certification packages on the system under test (SUT).

56

57

Figure 1 illustrates the overall configuration that this document will

58

help you create. This document describes configuration of the Portable

59

Computer device in the figure. It presupposes the existence of a local

60

LAN that the portable computer can use for external connections, as well

61

as the availability of at least one SUT for testing at the end of the

62

process. (Note that the Internet connection is required for initial

63

setup, but a properly-configured MAAS server does not need this

64

connection to bring up SUTs.) Once configured, you will be able to move

65

the portable computer from one site to another, repopulating the MAAS

66

LAN at each site.

67

68

.. figure:: images/maniac-network.png

69

:alt: This document describes configuring a server that manages its own

70

subnet and connects to a wider network on another interface.

71

:width: 100%

72

73

Figure 1: Network structure in which the portable computer will reside

74

75

Hardware Required

76

=================

77

78

Before beginning, you should ensure that you have the following

79

hardware:

80

81

* Portable computer

82

83

- Ensure that the portable computer has two network interfaces. A

84

laptop with both Ethernet and wi-fi should suffice; or you can use a

85

USB network dongle to provide a second interface, particularly for a

86

NUC.

87

88

- Because testing sessions can last for hours, ensure that you have a

89

power brick; you should *not* run on battery power!

90

91

- You can install on a virtual machine in a more general-purpose

92

computer, but you'll have to pay careful attention to the network and

93

disk settings.

94

95

* System Under Test (SUT) that supports one of the power types MAAS

96

supports:

97

98

- American Power Conversion (APC) PDU

99

- Cisco UCS Manager

100

- Digital Loggers, Inc. PDU

101

- HP Moonshot - iLO Chassis Manager

102

- HP Moonshot - iLO (IPMI)

103

- IPMI

104

- Intel AMT

105

- Microsoft OCS - Chassis Manager

106

- SeaMicro 15000

107

- Sentry Switch CDU

108

- VMWare

109

- Virsh (virtual systems)

110

111

* Small gigabit switch (8 ports should be enough)

112

113

- For laptop with Wi-Fi: one Ethernet cable

114

115

- For NUC or laptop with dongle: two Ethernet cables

116

117

- For each SUT: one Ethernet cable for each NIC port including the BMC

118

119

* Monitor and keyboard for SUT (helpful, but not strictly required)

120

121

* Monitor, keyboard, and mouse for the MAAS system (a laptop's built-in

122

devices should be sufficient)

123

124

* Video cable for NUC (HDMI, Mini DisplayPort, or a converter like a

125

MiniDP to VGA)

126

127

* At least 1TB of disk space with which to mirror the Ubuntu archives,

128

if desired (an external USB3 hard disk may be used for this, if

129

necessary)

130

131

Note that these hardware requirements are geared toward a typical

132

testing environment. You may need to expand this list in some cases. For

133

instance, if you test multiple servers simultaneously, you may need

134

additional Ethernet ports.

135

136

Installing and Configuring Ubuntu

137

=================================

138

139

Once you've assembled the basic hardware for your portable system, you can

140

begin preparing it. The initial steps involve installing Ubuntu and setting

141

up its most basic network settings:

142

143

1. Install Ubuntu 14.04 (Trusty Tahr) to the portable system

144

145

- The Desktop version of Ubuntu is recommended because it enables you

146

to easily access the MAAS Dashboard locally without needing a third

147

system.

148

149

- If you choose to use the Server version, you will probably want to

150

install the desktop on top of that as it simplifies MAAS access.

151

152

- This guide assumes the use of Ubuntu 14.04. Although another version

153

may work, some details will differ.

154

155

#. Boot the portable computer and log in.

156

157

#. Configure your *external* network port:

158

159

- On a laptop, you can use the Wi-Fi (usually ``wlan0``) port as the

160

external port.

161

162

- If you need to use both a built-in Ethernet port and an Ethernet

163

dongle, it's best to use the latter as your external port.

164

165

- In most cases, no explicit configuration of the external port is

166

necessary because the Ubuntu Desktop system will have set it up to

167

use DHCP, which is appropriate. You can adjust it if necessary,

168

though.

169

170

- In theory, you can configure the external network either via

171

``/etc/network/interfaces`` or by using the Desktop's Network Manager

172

tool.

173

174

#. Configure your portable computer's *internal* port. This guide assumes

175

use of ``eth0`` and a static IP address of 172.16.0.1/22 on this port.

176

177

- If possible, configure the computer's built-in Ethernet port, rather

178

than a plug-in dongle, as the internal port.

179

180

- You can either edit ``/etc/network/interfaces`` or use the GUI

181

Network tool in the System Settings panel to configure the internal

182

port. An example ``/etc/network/interfaces`` configuration resembles

183

the following::

184

185

auto eth0

186

iface eth0 inet static

187

address 172.16.0.1

188

broadcast 172.16.3.255

189

netmask 255.255.252.0

190

191

- If necessary or desired, you may use a different IP address on the

192

*internal* port. If your portable computer will move from one

193

*external* network to another, be sure to consider all its likely

194

*external* addresses when deciding on its *internal* address and

195

netmask.

196

197

- Do not specify a gateway for the private internal LAN; doing so will

198

create confusion when trying to access the Internet via the external

199

port.

200

201

- If you have issues installing packages, check ``route -n`` and make

202

sure you don't have a gateway route to the private LAN.

203

204

- Using a /22 or wider network is advisable for the internal network.

205

When so configured, the setup script will use the final two of the

206

four resulting octet ranges (for instance, 172.16.2.x and 172.16.3.x

207

from 172.16.0.0/22) for DHCP addresses, leaving the first two ranges

208

(for instance, 172.16.0.x and 172.16.1.x) for static addresses -- for

209

instance, for the MAAS server itself, as well as anything else you

210

want to assign a static IP address (perhaps your BMCs).

211

212

- If you use a /22 or wider network, the MAAS server's address can be

213

anything within the first two ranges (for instance, 172.16.0.x or

214

172.16.1.x), which are not handled by the computer's own DHCP server.

215

If you use a /23 or /24 network, the MAAS server must be within the

216

first nine addresses of that range (for instance, 172.16.0.1 through

217

172.16.0.9), since the rest of the range is assigned by MAAS's DHCP

218

server.

219

220

- Once you've finished configuring this network port, be sure to

221

activate it. If you configured it by editing

222

``/etc/network/interfaces``, type ``sudo ifup eth0`` to activate it.

223

(Depending on your starting configuration, you might need to type

224

``sudo ifdown eth0`` or bring it down via your GUI tools before

225

bringing it up with its changed configuration.)

226

227

#. If you plan to mirror the Ubuntu archives locally, ensure you have

228

enough space in the ``/srv`` directory to hold your mirrors. As a

229

general rule of thumb, you should set aside about 150GB per release. If

230

necessary, mount an extra disk at ``/srv`` to hold your repository

231

mirror.

232

233

#. Update the software on your system to the latest versions available::

234

235

$ sudo apt-get update

236

$ sudo apt-get dist-upgrade

237

238

#. Reboot the computer. This enables you to begin using your updated kernel

239

(if it was updated) and ensures that your network settings will survive a

240

reboot.

241

242

.. _`Installing and Configuring MAAS`:

243

244

Installing and Configuring MAAS

245

===============================

246

247

Installing MAAS on the computer is quite straightforward; you simply use

248

APT. With MAAS installed, you can run the ``maniacs-setup`` script to

249

configure MAAS for use in an Ubuntu certification environment.

250

251

Installing MAAS

252

---------------

253

254

Configuring MAAS is described in generic terms at

255

`http://maas.ubuntu.com/docs/install.html <http://maas.ubuntu.com/docs/install.html>`_.

256

The more specific procedure for using MAAS in certification testing is:

257

258

#. Install the MAAS stable PPA

259

(`https://launchpad.net/~maas/+archive/ubuntu/stable <https://launchpad.net/~maas/+archive/ubuntu/stable>`_)::

260

261

$ sudo apt-add-repository ppa:maas/stable

262

263

Currently (July, 2015), Ubuntu 14.04 installs MAAS 1.5 by default. This

264

PPA holds version 1.8 of MAAS, which is the recommended version for

265

certification testing. (MAAS 1.7 is also acceptable.) Version 1.8 will

266

eventually become standard for Ubuntu 14.04, at which point this step

267

will become unnecessary.

268

269

#. Several scripts and configuration files, some of which are quite

270

lengthy, are available in the ``maas-cert-server`` package in the

271

hardware certification PPA. You can install the scripts and configuration files

272

as follows::

273

274

$ sudo apt-add-repository ppa:hardware-certification/public

275

$ sudo apt-get update

276

$ sudo apt-get install maas-cert-server

277

278

As of version 0.1.2, the ``maas-cert-server`` package includes a

279

dependency on MAAS, so installing ``maas-cert-server`` will also install

280

MAAS, as well as all of MAAS's dependencies.

281

282

Most of the ``maas-cert-server`` files will be installed in

283

subdirectories of ``/usr/share/maas-cert-server``, although a few

284

appear outside of that directory tree. (Subsequent steps describe how to

285

use these files.)

286

287

#. Verify that you've installed MAAS 1.8 from the PPA, rather than MAAS

288

1.5 or some other version::

289

290

$ dpkg -p maas | grep Version

291

292

If the wrong version is installed, fixing the problem (presumably a

293

misconfigured PPA) and upgrading may work. If you upgrade from an

294

earlier version of MAAS, be sure to select the option to upgrade all the

295

configuration files when the package manager asks about this.

296

297

#. Edit the ``/etc/maas-cert-server/config`` file to be sure that the

298

variables it contains are correct. Specifically:

299

300

- ``INTERNAL_NET`` must point to your *internal* network device

301

(``eth0`` in this document).

302

303

- ``EXTERNAL_NET`` must point to your *external* network device

304

(``eth1`` in this documnt, but this might be ``wlan0`` if you're

305

using a laptop).

306

307

- Do not adjust other values without consulting with the Server

308

Certification Team.

309

310

- Note that there must *not* be spaces surrounding the equal signs

311

(``=``) in the assignments!

312

313

Running the Setup Script

314

------------------------

315

316

The certification script is called ``maniacs-setup``, and was installed as part

317

of the ``maas-cert-server`` package. Running this script will set up the MAAS

318

server with reasonable defaults for certification work; however, the script

319

will also ask you a few questions along the way::

320

321

$ sudo maniacs-setup

322

323

***************************************************************************

324

* Identified networks:

325

* INTERNAL: 172.16.0.1 on eth0

326

* EXTERNAL: 192.168.25.143 on eth1

327

*

328

* Is this correct (Y/n)?

329

330

Be sure your network assignments are correct at this point! If the script

331

complains about a problem, such as an inability to identify an IP address

332

or a default route being present on your internal network, go back and

333

review both your network settings and the contents of your

334

``/etc/maas-cert-server/config`` file to identify the cause and correct the

335

problem.

336

337

If you approve the settings, the script will display additional messages as

338

it begins to configure the MAAS server. Some of these messages are the

339

output of the programs it calls. For the most part this output can be

340

ignored, but if a problem occurs, be sure to report it in detail, including

341

the script's output.

342

343

Note that at all prompts for a "Y/N" response, the default value is

344

capitalized; if you press Enter, that default will be used.

345

346

The next question acquires a password for the administrative account, which

347

will have the same name as your default login name::

348

349

***************************************************************************

350

* A MAAS administrative account with a name of ubuntu is being

351

* created.

352

*

353

* Please enter a password for this account:

354

* Please re-enter the password for verification:

355

356

In most cases, you should enable NAT on your MAAS server; however, if

357

official policy at the site where the server will be used forbids the use

358

of NAT, you may opt to leave it disabled::

359

360

***************************************************************************

361

* NAT enables this computer to connect the nodes it controls to the Internet

362

* for direct downloads of package updates and to submit certification results

363

* to C3.

364

*

365

* You can configure this computer to automatically start NAT. If you do so, you

366

* can disable it temporarily by using the 'flushnat.sh' script or permanently

367

* by removing the reference to /usr/sbin/startnat.sh from /etc/rc.local.

368

*

369

* Do you want to set up this computer to automatically enable NAT (Y/n)?

370

371

Note that you can enable NAT on a one-time basis by running the

372

``startnat.sh`` script and disable it by running the ``flushnat.sh``

373

script. Both of these scripts come with the ``maas-cert-server`` package.

374

375

If your work site has poor Internet connectivity or forbids outgoing

376

connections, you must create a local mirror of the Ubuntu archives on your

377

MAAS server. These archives will be stored in the ``/srv`` directory, but

378

creating them takes a long time because of the amount of data to be

379

downloaded -- about 150 GB per release. For comparison, HD video consumes

380

1-8GiB per hour -- usually on the low end of that range for video streaming

381

services. As should be clear, the result will be significant network demand

382

that will degrade a typical residential DSL or cable connection for hours,

383

and possibly exceed your monthly bandwidth allocation. If you want to defer

384

creating a mirror, you should respond ``N`` to the following prompt, then

385

re-launch ``maniacs-setup`` with the ``\-\-mirror-archives`` (or ``-m``)

386

option later. In any event, you make your selection at the following

387

prompt::

388

389

***************************************************************************

390

* Mirroring an archive site is necessary if you'll be doing testing while

391

* disconnected from the Internet, and is desirable if your test site has

392

* poor Internet connectivity. Performing the mirroring operation takes

393

* time and disk space, though -- about 150 GiB per release mirrored.

394

* To defer this task, respond 'N' to the following question.

395

*

396

* Do you want to mirror an archive site for local use (y/N)? Y

397

398

If you opt to mirror the archive, the script will ask you to verify the

399

upstream mirror site::

400

401

* Identified upstream archive is:

402

* http://us.archive.ubuntu.com/ubuntu/

403

*

404

* Is this correct (Y/n)? y

405

406

If you respond ``n`` to this question, the script asks you to specify

407

another archive site. The script then asks you which Ubuntu releases to

408

mirror::

409

410

* Do you want to mirror precise (Y/n)? n

411

* Do you want to mirror trusty (Y/n)? y

412

* Do you want to mirror vivid (Y/n)? n

413

* Do you want to mirror wily (Y/N)? n

414

415

The list of releases changes as new versions become available and as old

416

ones drop out of supported status.

417

When the mirror process is done, you'll be asked if you want to configure

418

the computer to

419

automatically update its mirror every day, by modifying the

420

``/etc/cron.d/apt-mirror`` file. If you do not opt for automatic daily

421

updates, you can update your mirror at any time by typing ``sudo

422

apt-mirror``.

423

424

::

425

426

* Set up cron to keep your mirror up-to-date (Y/n)? y

427

* Cron should update your mirror every morning at 4 AM.

428

* You can adjust /etc/cron.d/apt-mirror manually, if you like.

429

430

Note that ``maniacs-setup`` configures the system to mirror AMD64, i386,

431

and source repositories because all three are required by the default APT

432

configuration. If you want to tweak the mirror configuration, you can do so

433

by editing the ``/etc/apt/mirror.list`` file -- but do so *after* finishing

434

with the ``maniacs-setup`` script, and then type ``sudo apt-mirror`` to

435

pull in any new directories you've specified. You can also configure the

436

computer to use its own local mirror, if you like::

437

438

* Adjust this computer to use the local mirror (Y/n)? y

439

440

The script then gives you the option to retrieve an image used for

441

virtualization testing. If your site has good Internet connectivity, you

442

may not need this image; but it's not a bad idea to have it on hand

443

just in case. Note that the script skips this prompt if it detects an image

444

already exists in ``/srv``. Although downloading the cloud image isn't

445

nearly as time-consuming as mirroring the archives, it can take long

446

enough that you may want to defer this action. You can download the

447

cloud image later by launching ``maniacs-setup`` with the

448

``\-\-download-virtualization-image`` (or ``-d``) option.

449

450

::

451

452

***************************************************************************

453

* An Ubuntu cloud image is required for virtualization tests. Having such an

454

* image on your MAAS server can be convenient, but downloading it can take

455

* a while (it's about 250MiB).

456

*

457

* To defer this task, respond 'N' to the following question.

458

*

459

* Do you want to copy a cloud image for the vitualization tests (Y/n)?

460

461

You can customize the site that MAAS tells nodes to use for their

462

repositories. If you mirrored a repository, the script points nodes to

463

itself (via its internal IP address); but if you did not mirror a

464

repository, the script should point your nodes to the same site used by the

465

MAAS server itself. In either case, you can press the Enter key to accept

466

the default or enter a new value::

467

468

***************************************************************************

469

* MAAS tells nodes to look to an Ubuntu repository on the Internet. You

470

* can customize that site by entering it here, or leave this field blank

471

* to use the default value of http://172.16.0.1/ubuntu.

472

*

473

* Type your repository's URL, or press the Enter key:

474

475

At this point, the script gives you the option of telling MAAS to begin

476

importing its boot resources -- images it uses to enlist, commission, and

477

start nodes. This process can take several minutes to over an hour to

478

complete, so the script gives you the option of deferring this process::

479

480

***************************************************************************

481

* MAAS requires boot resource images to be useful; however, importing them

482

* can take a LONG time. You can perform this task now or defer it until

483

* later (or do it manually with the MAAS web UI).

484

*

485

* Do you want to import boot resources now? (Y/n)

486

487

If you choose to defer this process, MAAS may begin it automatically in the

488

background. If this fails and you want to initiate it manually later, you

489

can use the MAAS web UI or launch ``maniacs-setup`` with the

490

``\-\-import-boot-resources`` (or ``-i``) option.

491

492

When MAAS has finished importing boot resources, the

493

script helps you import the point-release images used for certification;

494

however, you are first asked which series you want to import::

495

496

***************************************************************************

497

* Ubuntu hardware certification is done using point-release images. These

498

* can take a LONG time to download. You can do so now or defer this task.

499

*

500

* Do you want to import point-release images now (Y/n)? y

501

*

502

* Do you want to import 15.10 (1 image) (y/N)? n

503

* Do you want to import the 14.04 series (4 images) (Y/n)? y

504

* Do you want to import the 12.04 series (6 images) (y/N)? y

505

506

Whenever you respond ``Y`` to a question about a particular version or

507

series, the script proceeds to download and register the images. (The

508

relevant output has been omitted from the preceding example.) If an image

509

is already installed, ``maniacs-setup`` skips that image. Certification

510

uses only LTS images; however, non-LTS images, such as 15.10, may be made

511

available for testing and as a way to "preview" the features of

512

future LTS series.

513

514

If you're running MAAS 1.8.2 or later, ``maniacs-setup`` registers the most

515

recent point-release image in any series you download as the default OS for

516

deployments.

517

518

Again, this process can take a while, especially if you opt to import the

519

12.04 images. If you want to skip this step for now and return to it, you

520

can; you should re-launch ``maniacs-setup`` with its

521

``\-\-update-point-releases`` (or ``-u``) option when you're ready to

522

download these images.

523

524

Finally, the script announces it's finished its work::

525

526

***************************************************************************

527

* The maniacs-setup script has finished!

528

529

In addition to setting the options for which it prompts, ``maniacs-setup``

530

adjusts some other details of which you should be aware:

531

532

- SSH keys are generated for your user account and added to the MAAS

533

server. These keys enable you to log in to nodes that MAAS deploys from

534

your regular account on the MAAS server.

535

536

- Any keys in your ``~/.ssh/authorized_keys`` file on the portable are also

537

added to the MAAS setup. Again, this simplifies login.

538

539

- The portable computer's SSH server configuration is relaxed so that

540

changed host keys do not block outgoing connections. This change is

541

*insecure*, but is a practical necessity because your internal network's

542

nodes will be redeployed regularly. You should keep this setting in mind

543

and minimize your use of this computer to SSH to external sites.

544

545

- MAAS is configured to tell nodes to install the Canonical Certification

546

Suite whenever they're deployed. This detail increases deployment time

547

compared to a generic MAAS installation.

548

549

Checking the MAAS Configuration

550

-------------------------------

551

552

At this point, MAAS should be installed and configured; however, it's worth

553

verifying the most important options in the MAAS Web UI. You may also want

554

to modify a few settings. To do so, follow these steps:

555

556

#. Verify you can access the MAAS Dashboard:

557

558

- Launch a browser and point it to \http://172.16.0.1/MAAS (your

559

internal port).

560

561

- You should also be able to access this by default on the

562

external port, too.

563

564

- If you provide the computer with a hostname in DNS or ``/etc/hosts``,

565

you should be able to access it via that name, as well.

566

567

- You should see a login prompt.

568

569

#. Log in to the Dashboard using your regular username and the password you

570

gave to the setup script.

571

572

#. Click Images near the top of the MAAS web page. This page will show the Ubuntu images that are available on the server. The setup script imports a 14.04 image for AMD64, as well as custom images for every 14.04 point release. You may need to take additional actions in some cases:

573

574

- If you see a blue circle next to an image, it did not import

575

correctly. You can also check the Clusters page to verify the status

576

of your image downloads. A successful image import will show Synced

577

under Images.

578

579

- If you need to support architectures other than AMD64, you must check

580

that architecture and click Apply Changes. This process will probably

581

take several minutes to complete.

582

583

- If you need to import i386 point-release images, you must import them

584

manually, as described in Appendix B.

585

586

#. Click the Clusters link near the top of the web page so you can review

587

the DHCP options:

588

589

#. Click the cluster name for the cluster controller (Cluster Master in

590

this example):

591

592

.. image:: images/clusters-page.png

593

:width: 98%

594

595

#. Mouse over the *internal* (normally ``eth0``) network

596

interface. (If you don't see your internal interface listed, click

597

the "Add Interface" button to add it.) You should see a pair of

598

icons appear, one to edit the interface and one to delete it. Click

599

the former, then review the following items:

600

601

- Be sure that "Interface" is set to your internal port and that

602

"Management" is set to "DHCP and DNS."

603

604

- Review the various IP addresses and netmasks.

605

606

- Click "Save Interface" if you made any changes.

607

608

#. Click Settings near the top of the page to load the MAAS Settings page,

609

where you review several miscellaneous MAAS details. If you change any

610

settings, be sure to click the associated "Save" button within that

611

section. Unfortunately, each save button is section-specific and won't

612

save changes made in other sections of that page.

613

614

Testing the MAAS Server

615

=======================

616

617

At this point, your MAAS server should be set up and configured correctly.

618

To test it, follow these steps:

619

620

#. Prepare a computer by configuring it to boot via PXE. This computer

621

need not be a computer you plan to certify; anything that can

622

PXE-boot should work, although to fully test the MAAS server, the

623

test system should provide IPMI or some other power-control tool that

624

MAAS supports.

625

626

#. Connect the test computer to the portable computer's *internal* network

627

and power it on.

628

629

- The test computer should PXE-boot from the portable MAAS computer.

630

631

- This first boot should be to the enlistment image, which provides

632

some very basic information to the MAAS server. Once the node powers

633

itself off you should see it listed in the MAAS nodes list

634

(\http://localhost/MAAS/#/nodes/ or, on MAAS 1.7,

635

\http://localhost/MAAS/nodes/) with a Status field of "New."

636

637

- Note that you will have to refresh the nodes list as it does not

638

refresh itself to list new data.

639

640

#. Click on the node's hostname to view the node's summary page.

641

642

#. If desired, click the node's hostname near the upper-left corner of the

643

page. This will enable you to change the hostname to something

644

descriptive, such as the computer's model number. Click "Save" when

645

you've made your changes.

646

647

#. If necessary, click "Edit" in the Machine Summary section to change the

648

architecture of the machine. Click "Save Changes" when you're done.

649

650

#. If necessary, change the Power Type in the Power section of the page.

651

This may necessitate setting an IP address, MAC address, password, or

652

other information, depending on the power control technology in use.

653

Click "Save Changes" when you're done.

654

655

#. Click "Take Action" near the top-right corner of the page, followed by

656

"Commission Node" from the resulting drop-down menu. You must then click

657

"Go."

658

659

- The node should power on again. This time you'll see it PXE-boot the

660

commissioning image. Note that if your test system lacks a BMC or

661

other means to remotely control its power, you must manually power it

662

on.

663

664

- The node should do a bit more work this time before powering off

665

again.

666

667

- Once it's done, the UI will show a Status of "Ready."

668

669

#. Once the system powers off after commissioning, click "Take Action"

670

followed by "Deploy." You must then click "Go" to confirm this action.

671

672

- The node should power on again (or you will have to control it

673

manually if it lacks a BMC). This time it will take longer to finish

674

working, as MAAS will install Ubuntu and the certification suite on

675

the system.

676

677

- Once it's done, the computer will reboot into its installed image.

678

679

- Log into the node from the MAAS server by using SSH, as in ``ssh

680

testnode`` if you've given the node the name ``testnode``.

681

682

- In the node, type ``canonical-certification-server``. The

683

certification suite software should run. You can type Ctrl+C to exit;

684

at this point, it's sufficient to know that it installed correctly.

685

686

If any of these steps fail, you may have run into a MAAS bug; your test

687

computer may have a buggy PXE, IPMI, or other subsystem; or you may have

688

misconfigured something in the MAAS setup. You may want to review the

689

preceding sections to verify that you configured everything correctly.

690

To help in debugging problems, the node status page includes a section

691

entitled Latest Node Events with a summary of the last few events

692

related to the node. (You must refresh the page to see new events.)

693

694

.. raw:: pdf

695

696

PageBreak

697

698

Appendix A: Updating Fixed Point Release Images

699

===============================================

700

701

From time to time, Canonical updates the LTS versions of Ubuntu with new

702

point releases, such as 14.04.1, 14.04.2, and so on. Because you must run

703

the certification tests on the latest point release, updating your MAAS

704

server with the latest point releases will become necessary, sooner or

705

later. This task can be accomplished with MAAS 1.7 or 1.8 by installing

706

custom images.

707

708

The ``maniacs-setup`` script automatically downloads and installs all the

709

available point-release images at the time you first run it. After a new

710

point release is made, you can re-run the script with the

711

``\-\-update-point-releases`` (or ``-u``) option to have the script install

712

the new release::

713

714

$ sudo apt-get install maas-cert-server

715

$ sudo maniacs-setup --update-point-releases

716

717

The script will skip most of the setup steps and proceed to asking you

718

which point-release images to download and install. When you select a

719

series, only those point-release images that have not yet been installed

720

from that series will be downloaded. Note that if you're running

721

``maas-cert-server`` version 0.2.9 or earlier, you should update to the

722

latest version before updating your point releases. Version 0.2.10

723

introduced the ability to dynamically determine what Ubuntu point-release

724

images are available for download; earlier versions used a hard-coded list,

725

and so will miss updates beyond Ubuntu 14.04.3.

726

727

If a particular point release is giving you problems, you can delete it

728

using the MAAS web UI and then update your point-release images as just

729

described; this will refresh the image to the latest available version.

730

Similarly, if the Server Certification Team releases new images, you should

731

first delete the old ones using the web UI and then update your point

732

releases.

733

734

Note that before you can install a custom image for any given architecture,

735

you must have first imported at least one image for that architecture via

736

the conventional means. The ``maniacs-setup`` script detects whether you've

737

installed the standard i386 images and will install i386 point-release

738

images if and only if the standard i386 images are already installed.

739

Currently, only AMD64 and i386 point-release images are available.

740

741

742

.. raw:: pdf

743

744

PageBreak

745

746

Appendix B: Adding i386 Support

747

===============================

748

749

By default, the ``maniacs-setup`` script supports only AMD64 (64-bit,

750

x86-64) nodes. (If you created a local mirror, it includes i386/x86

751

binaries because they're needed by some 64-bit packages.) If you expect to

752

run certification tests on i386 (32-bit, x86) computers, though, you must

753

add support for such systems in MAAS:

754

755

#. In the MAAS web UI, click the Images tab.

756

757

#. Select "i386" in the "Architecture" column.

758

759

#. Click "Apply changes." The standard MAAS i386 images will download. This

760

process can take several minutes, and perhaps over an hour on a slow

761

Internet connection.

762

763

#. Re-run the ``maniacs-setup`` script, but add the

764

``\-\-update-point-releases`` option to the script, as described in

765

Appendix A. This will cause the script to download and add the

766

point-release images for i386 systems.

767

768

That's it. You can add support for ppc64el, ARM64, or other architectures

769

in a similar way; however, there are currently no point-release images for

770

these architectures. Please consult the Server Certification Team if you

771

need to certify systems using these CPUs.

772

773

.. raw:: pdf

774

775

PageBreak

776

777

Appendix C: Performing a Partial Restore

778

========================================

779

780

If the MAAS server's support files (the PXE boot images and related

781

files) become damaged, PXE-booting SUTs may fail. The SUT may fail to

782

retrieve PXE boot images or the boot may fail with any number of

783

symptoms later in the process. If you're unable to discover a cause and

784

solution through less drastic means, one possible recovery procedure is

785

to restore those files to a fresh state; however, be aware that this

786

procedure will *destroy all existing node definitions.* Thus (and because

787

the solution involves downloading new boot images, which can be

788

time-consuming), you should attempt this solution only as a last resort.

789

Steps 1 and 6-7 of the following procedure are the minimum required;

790

steps 2-5 make for a more thorough cleansing of the system. The overall

791

procedure is:

792

793

#. Click the Clusters link in the MAAS server's web interface (to reach

794

the server's ``/MAAS/clusters/`` page).

795

796

#. Click the small trash can icon that appear near the right side of the

797

page associated with your malfunctioning cluster when you mouse over it,

798

and then confirm the operation. This will delete the cluster

799

controller's definition.

800

801

#. Delete the contents, including all subdirectories, of the

802

``/var/lib/maas/boot-resources`` directory on the portable server.

803

804

#. In a shell, reconfigure the ``maas-cluster-controller`` and

805

``maas-region-controller`` packages::

806

807

$ sudo dpkg-reconfigure maas-cluster-controller

808

$ sudo dpkg-reconfigure maas-region-controller

809

810

You should not need to adjust the default values.

811

812

5. Reset the cluster controller's DHCP and DNS options.

813

814

6. If necessary or desired, adjust the images you want to import.

815

816

7. Re-run the ``maniacs-setup`` script with the

817

``\-\-update-point-releases`` option, as described in Appendix A, to

818

refresh your point-release images.

819

820

This procedure should restore your ability to PXE-boot your SUTs.

821

822

.. raw:: pdf

823

824

PageBreak

825

826

Appendix D: Glossary

827

====================

828

829

The following definitions apply to terms used in this document.

830

831

1Gbps

832

1 Gigabit - Network speed for Gigabit Ethernet (1000Mbps).

833

834

10Gbps

835

10 Gigabit - Network speed for 10 Gigabit Ethernet (10,000Mbps).

836

837

BMC

838

Baseboard Management Controller -- A device in many server models

839

that allows remote in- and out-of-band management of hardware.

840

841

DHCP

842

Dynamic Host Control Protocol -- method for providing IP addresses

843

to the SUTs.

844

845

IPMI

846

Intelligent Platform Management Interface -- A technology for

847

remotely connecting to a system to perform management functions.

848

849

LAN

850

Local Area Network -- the network to which your SUTs are connected. The

851

LAN does not need to be Internet accessible (though that is preferable if

852

possible).

853

854

MAAS

855

Metal as a Service -- a Canonical product for provisioning systems

856

quickly and easily.

857

858

NIC

859

Network Interface Card -- the network device(s).

860

861

NUC

862

A small form-factor PC product from Intel.

863

864

PXE

865

Pre-boot Execution Environment -- A technology that allows you to

866

boot a system using remote images for easy deployment or network-based

867

installation.

868

869

SUT

870

System Under Test -- The machine you are testing for certification.