Getting There

You can access the Mozpool API within releng on any of the imaging servers. Currently, those are named mobile-imaging-###.p#.releng.scl.mozilla.com. So, try http://mobile-imaging-005.p5.releng.scl3.mozilla.com

Layers

Mozpool is divided into three layers, as described in ReleaseEngineering/Mozpool. Those three layers are easy to spot in the web UI, as each is a different color. Mozpool (requests) is blue, Lifeguard (device state tracking) is pink, and BMM (low-level device settings) is green. You'll use different layers to do different operations.

In each layer, you'll see a list of objects (requests or devices, depending on the layer) and a toolbar at the bottom. The toolbar contains "tabs" (bracketed with [..]) separating the operations you can perform on that page. Each tab has a small bit of help text to remind you how it works.

Mozpool

The Mozpool page displays all open requests, or if "Include closed requests" is checked, *all* requests.

The "New Request" tab allows you to create a new request. Specify the parameters limiting the device you want, and the time you want to reserve it for. Note that this time begins when you request the device, not when it's ready, so factor in imaging time to your estimate. Enter an email address for "assignee", and enter a B2G base URL for the B2G image you'd like to use. You will see your request appear immediately, along with the state of the assigned device. Once that is "ready", your device is ready to go.

The "Close Requests" and "Renew Requests" tabs both operate on existing, open requests. The first will close selected requests, releasing them before their appointed expiration time. The second allows you to extend the expiration time of the existing requests. Note that the time you enter here is not added to the existing time -- instead, it just sets a new expiration time starting when you click the button.

Lifeguard

The lifeguard page displays all known devices, along with their current state, comments, and other relevant information. On the right are links to the device's logs and its inventory page. The logs can be invaluable in figuring out what's going wrong with a device. Make a point of looking at logs for operational devices, so you know what to expect.

Remember, lifeguard is a mid-level tool, so this gets a little technical, and requires a bit of understanding of how the system works.

Please

The first tab, "Please..", allows you to request operations from the selected devices. Devices that are busy doing something else will ignore such requests. You can also set comments on the selected devices by checking the box next to "Update Comments". You could use this, for example, to say "testing Android image - bug 823456."

The "please" options are:

please_pxe_boot

Drop power to the device and restore it, configuring things so that it boots off the network ("PXE Boots") when it start up. This is how the magic happens. The PXE Config you select will dictate the details of what happens (see below), but the big picture is that the device boots an Ubuntu system and runs some shell scripts which communicate their progress back to Lifeguard. In most cases, these shell scripts install images on the sdcard.

please_power_cycle

Drop power to the device and restore it, then wait until the device is pingable again. This is the equivalent of switching the power to your desktop off, counting to 5, and switching it back on. The PXE Config is ignored in this case.

The PXE Configs can change frequently, and are versioned sequentially (so you should usually use the highest-numbered) but will include at least:

panda-android.*

install the latest Android image

panda-b2g.*

install B2G (see below!)

maintenance.*

stay in the Ubuntu image and allow SSH logins (username cltbld)

For Android, the image to use is implicit in the PXE configs. For B2G, however, the shell script needs to know *which* B2G image to install. It gets that from the Boot Config, which is a JSON string containing, in this case, a "b2gbase" key. This should contain a URL to a directory containing B2G image tarballs. In the UI, the JSON part is conveniently already filled in, so you only need to add the URL.

Whichever option you pick, you'll see the device cycle through states as the process progresses. It should finish in the "ready" state, or (after some retries) end up in a failed_ state. See ReleaseEngineering/Mozpool/How To Interpret Device State in Mozpool for help deciphering these states.

Remember, at this level you're working behind Mozpool's back. When a device enters the "ready" state, Mozpool will wonder what's going on, and reset it to the "free" state, then potentially allocate it to another user. If you don't want this to happen, you'll need to take steps to ensure that - best is to request the device yourself beforehand.

Force State

This tab lets you tell Lifeguard what state a device is in. Doing so does not touch the actual device at all -- it just changes Lifeguard's notion of the state.

Comemnts

The "Comments" tab allows you to edit comments for devices without changing anything else. Note that you can *clear* comments by checking the box but leaving the text empty.

BMM

The BMM page handles low-level details of devices. It, too, displays a list of devices, but the details are different: MAC address, assigned imaging server, environment, relay information, and so on.

The first tab lets you control the power on a device. You can power-cycle it or just turn it off. As with the lifeguard options, you can add comments at the same time if you'd like.

The second tab lets you PXE boot a device. This is similar to the Lifeguard PXE boot process, except that Lifeguard won't track the device's state transitions. You probably don't want to use this tab.

The "Environment" tab lets you set the environment for selected devices.

The "Comemnts" tab is the same as for Lifeguard. Just conveniently available here, too.

Quick Guides

"OK, that's all well and good, but I'm kind of in a rush here, so can you just tell me how to .."

move a device into or out of the staging pool

Go to the UI, click the BMM (green) block, and click the "Environment" tab. Select the device(s), type "staging" or "production" (or whatever environment you want to move them to), and click the button.

request a device for a developer loan

Go to the UI, click the Mozpool (blue) block, and enter the parameters for the request. Most likely, this is "any" device, drawn from a particular environment. Select a suitable request duration, enter the user's email address for assignee, and fill in the B2G Base for the image the user would like. Click the button, and when the request is up and ready, send the user the device name and access information.

lock out a device so Mozpool ignores it

Generally, this should be done with a request, but if you must:

Go to the UI, click the Lifeguard (pink) block, and click the "Force State" tab. Enter "locked_out", select the device(s), and click the button.

re-image a device I've already requested

Go to the UI, click the Lifeguard (pink) block, select the device(s), and select the "Please.." state. Use the "please_pxe_boot" option, with the PXE Config appropriate to the image you want. If that image requires boot config (e.g., B2G), fill that in as well. Click the button, and either wait for the device's state to become "ready", or click the device's log link and watch its progress to that state.

Remember that this hardware is temperamental, and retries are nothing to be alarmed about. However, Lifeguard has a hard time telling hardware error from human error, so if you're seeing a lot of retries, check the logs to see if you fat-fingered the boot config or chose the wrong PXE config or something like that.

manually control power on a device

Go to the UI, click the BMM (green) block, select the device(s), select the "Power Control" tab, and click "Power Cycle" or "Power Off".