Python AMT Tools Documentation

Transcription

1 Python AMT Tools Documentation Release Sean Dague Jan 14, 2018

2

3 Contents 1 Python AMT Tools Background Hardware that includes AMT Configuring AMT amtctrl Futures Installation 5 3 Usage 7 4 Contributing Types of Contributions Get Started! Pull Request Guidelines Tips Credits Development Lead Contributors History ( ) ( ) ( ) ( ) ( ) ( ) ( ) Indices and tables 17 i

4 ii

5 Python AMT Tools Documentation, Release Contents: Contents 1

6 Python AMT Tools Documentation, Release Contents

7 CHAPTER 1 Python AMT Tools Tools for interacting with Intel s Active Management Technology 1.1 Background AMT is a light weight hardware control interface put into some Intel based laptops and desktops as a tool for corporate fleets to manage hardware. It provides the basics of power control, as well as remote console via VNC. It functions by having a dedicated service processor sniff traffic off the network card on specific ports before it gets to the operating system. Some versions of Intel NUC boxes have AMT, which make them ideal candidates for building a reasonable cluster in your basement. There was once a tool called amttool which let you interact with these systems from Linux. This used the SOAP interface to AMT. That was removed in v9 of the firmware, which means it no longer works with modern AMT in the field. The interface that remains is CIM, a standard from the DMTF that builds XML models for all the things. There exist very few examples for how to make this work on the internet, with one exception: the OpenStack Baremetal (Ironic) service. It has native support for AMT hardware control. This project is derivative work from Ironic. The heavy lifting of understanding all the CIM magic incantations, and oh the magic they are, comes from that code. Refactored for a more minimal usage. 1.2 Hardware that includes AMT AMT is branded as vpro in products by Intel. It is found in many Intel based laptops. There are also specific models of Intel NUC that include vpro. Intel NUC KIT Core Processor BLKNUC5I5MYHE This code gets tested with 5i5MYHE NUCs as well as an older NUC that I have laying around. 3

8 Python AMT Tools Documentation, Release Configuring AMT AMT must be enabled in the BIOS before it can be used externally. This is done by pressing Ctrl-P during initial boot. Initial user / pass is admin / admin. You will be required to create a new admin password that has at least 1: number, capital letter, and non alphanumeric symbol. One you do that, reboot and you are on your way. 1.4 amtctrl The amt library installs a binary amtctrl for working with AMT enabled machines machine enrollment To simplify the control commands amtcrtl has a machine registry. New machines are added via: amtctrl add <name> <address> <amtpassword> You can see a list of all machines with: amtctrl list And remove an existing machine with: amtctrl rm <name> controlling machines Once machines are controlled you have a number of options exposed: amtctrl <name> <command> Command is one of: on - power on the machine off - power off the machine reboot - power cycle the machine pxeboot - set the machine to pxeboot the next time it reboots, and reboot the machine. This is extremely useful if you have install automation on pxeboot. status - return power status as an ugly CIM blob (TODO: make this better) 1.5 Futures More extensive in tree testing (there currently is very little of this) Retry http requests when they fail. AMT processors randomly drop some connections, built in limited retry should be done. Fault handling. The current code is very optimistic. Hence, the 0.x nature. Remove console control. There are AMT commands to expose a VNC remote console on the box. Want to support those. 4 Chapter 1. Python AMT Tools

9 CHAPTER 2 Installation At the command line: $ easy_install amt Or, if you have virtualenvwrapper installed: $ mkvirtualenv amt $ pip install amt 5

10 Python AMT Tools Documentation, Release Chapter 2. Installation

11 CHAPTER 3 Usage To use Python AMT Tools in a project: import amt 7

12 Python AMT Tools Documentation, Release Chapter 3. Usage

13 CHAPTER 4 Contributing Contributions are welcome, and they are greatly appreciated! Every little bit helps, and credit will always be given. You can contribute in many ways: 4.1 Types of Contributions Report Bugs Report bugs at If you are reporting a bug, please include: Your operating system name and version. Any details about your local setup that might be helpful in troubleshooting. Detailed steps to reproduce the bug Fix Bugs Look through the GitHub issues for bugs. Anything tagged with bug is open to whoever wants to implement it Implement Features Look through the GitHub issues for features. Anything tagged with feature is open to whoever wants to implement it. 9

14 Python AMT Tools Documentation, Release Write Documentation Python AMT Tools could always use more documentation, whether as part of the official Python AMT Tools docs, in docstrings, or even on the web in blog posts, articles, and such Submit Feedback The best way to send feedback is to file an issue at If you are proposing a feature: Explain in detail how it would work. Keep the scope as narrow as possible, to make it easier to implement. Remember that this is a volunteer-driven project, and that contributions are welcome :) 4.2 Get Started! Ready to contribute? Here s how to set up amt for local development. 1. Fork the amt repo on GitHub. 2. Clone your fork locally: $ git clone git@github.com:your_name_here/amt.git 3. Install your local copy into a virtualenv. Assuming you have virtualenvwrapper installed, this is how you set up your fork for local development: $ mkvirtualenv amt $ cd amt/ $ python setup.py develop 4. Create a branch for local development: $ git checkout -b name-of-your-bugfix-or-feature Now you can make your changes locally. 5. When you re done making changes, check that your changes pass flake8 and the tests, including testing other Python versions with tox: $ flake8 amt tests $ python setup.py test $ tox To get flake8 and tox, just pip install them into your virtualenv. 6. Commit your changes and push your branch to GitHub: $ git add. $ git commit -m "Your detailed description of your changes." $ git push origin name-of-your-bugfix-or-feature 7. Submit a pull request through the GitHub website. 10 Chapter 4. Contributing

15 Python AMT Tools Documentation, Release Pull Request Guidelines Before you submit a pull request, check that it meets these guidelines: 1. The pull request should include tests. 2. If the pull request adds functionality, the docs should be updated. Put your new functionality into a function with a docstring, and add the feature to the list in README.rst. 3. The pull request should work for Python 2.6, 2.7, 3.3, and 3.4, and for PyPy. Check amt/pull_requests and make sure that the tests pass for all supported Python versions. 4.4 Tips To run a subset of tests: $ python -m unittest tests.test_amt 4.3. Pull Request Guidelines 11

16 Python AMT Tools Documentation, Release Chapter 4. Contributing

17 CHAPTER 5 Credits 5.1 Development Lead Sean Dague <sean@dague.net> 5.2 Contributors None yet. Why not be the first? 13

18 Python AMT Tools Documentation, Release Chapter 5. Credits

19 CHAPTER 6 History ( ) add support for hybernate power state (thanks Chen Rotem Levy) ensure hostdb is not world readable when created (thanks bodo-riediger) ( ) add support for -p flag to prompt for password and bypass hostdb nice errors to the user when auth fails ( ) add support for stand-by power state (thanks Chen Rotem Levy) ( ) python 2 fixes for python 3 issues (thanks Chen Rotem Levy) ( ) python 3 fixes and testing (thanks Rixillo) 15

20 Python AMT Tools Documentation, Release ( ) python 3 print fix (thanks Mike Nawrocki) add set_next_boot and change_boot_order_request (thanks John L. Villalovos) ( ) First release on PyPI. 16 Chapter 6. History

21 CHAPTER 7 Indices and tables genindex modindex search 17