| 1 | <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> |
|---|
| 2 | <html xmlns="http://www.w3.org/1999/xhtml"> |
|---|
| 3 | <head> |
|---|
| 4 | <meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> |
|---|
| 5 | <meta http-equiv="Content-Style-Type" content="text/css" /> |
|---|
| 6 | <meta name="generator" content="pandoc" /> |
|---|
| 7 | <title>Getting started with Ansible</title> |
|---|
| 8 | <style type="text/css">code{white-space: pre;}</style> |
|---|
| 9 | <link rel="stylesheet" href="../../style.css" type="text/css" /> |
|---|
| 10 | </head> |
|---|
| 11 | <body> |
|---|
| 12 | <div id="header"> |
|---|
| 13 | <h1 class="title">Getting started with Ansible</h1> |
|---|
| 14 | </div> |
|---|
| 15 | <div id="TOC"> |
|---|
| 16 | <ul> |
|---|
| 17 | <li><a href="#install-packages"><span class="toc-section-number">1</span> Install packages</a></li> |
|---|
| 18 | <li><a href="#download-the-workshop-kit-files"><span class="toc-section-number">2</span> Download the workshop-kit files</a></li> |
|---|
| 19 | <li><a href="#configure-ansible"><span class="toc-section-number">3</span> Configure ansible</a></li> |
|---|
| 20 | <li><a href="#first-run-network-reconfiguration"><span class="toc-section-number">4</span> First run: network reconfiguration</a><ul> |
|---|
| 21 | <li><a href="#how-does-it-work"><span class="toc-section-number">4.1</span> How does it work?</a></li> |
|---|
| 22 | </ul></li> |
|---|
| 23 | <li><a href="#second-run-platform-configuration"><span class="toc-section-number">5</span> Second run: platform configuration</a></li> |
|---|
| 24 | <li><a href="#third-run-full-configuration"><span class="toc-section-number">6</span> Third run: full configuration</a></li> |
|---|
| 25 | <li><a href="#appendix"><span class="toc-section-number">7</span> Appendix</a><ul> |
|---|
| 26 | <li><a href="#pointing-your-apt-to-your-local-apt-cacher-instance"><span class="toc-section-number">7.1</span> Pointing your apt to your local apt-cacher instance</a></li> |
|---|
| 27 | <li><a href="#using-git"><span class="toc-section-number">7.2</span> Using git</a><ul> |
|---|
| 28 | <li><a href="#configure-git"><span class="toc-section-number">7.2.1</span> Configure git</a></li> |
|---|
| 29 | </ul></li> |
|---|
| 30 | </ul></li> |
|---|
| 31 | <li><a href="#obtaining-workshop-kit-files-with-tarballs"><span class="toc-section-number">8</span> Obtaining workshop kit files with tarballs</a><ul> |
|---|
| 32 | <li><a href="#from-a-tarball"><span class="toc-section-number">8.1</span> From a tarball</a></li> |
|---|
| 33 | </ul></li> |
|---|
| 34 | </ul> |
|---|
| 35 | </div> |
|---|
| 36 | <p>Be sure you connect via ssh to your MacMini as the nsrc user. Don't become root.</p> |
|---|
| 37 | <p>Starting with a fresh Ubuntu 12.04.x install, we will set up ansible to get the workshop server to configure itself.</p> |
|---|
| 38 | <h1 id="install-packages"><a href="#install-packages"><span class="header-section-number">1</span> Install packages</a></h1> |
|---|
| 39 | <p>Add the <a href="https://launchpad.net/~rquillo/+archive/ansible">ansible PPA</a> to get a more recent version of ansible. Hit Enter when prompted.</p> |
|---|
| 40 | <pre><code>sudo apt-get install python-software-properties |
|---|
| 41 | sudo add-apt-repository ppa:rquillo/ansible |
|---|
| 42 | sudo apt-get update |
|---|
| 43 | sudo apt-get install ansible git</code></pre> |
|---|
| 44 | <p>Make a note of the ansible version installed. These scripts were tested using ansible=1.3.3-precise1. Although the author strives for backwards compatibility, sometimes later versions may change how scripts work.</p> |
|---|
| 45 | <h1 id="download-the-workshop-kit-files"><a href="#download-the-workshop-kit-files"><span class="header-section-number">2</span> Download the workshop-kit files</a></h1> |
|---|
| 46 | <p>This should be done as the non-root (nsrc) user, in your home directory. How you do it depends on whether you have been given full access to the git repository. For purposes of class we will use git over http with passwords.</p> |
|---|
| 47 | <pre><code>cd |
|---|
| 48 | git clone http://trainers@wsnoc.nsrc.org:8000/nsrc/workshop-kit.git</code></pre> |
|---|
| 49 | <p>When prompted for a password use the one given in class.</p> |
|---|
| 50 | <h1 id="configure-ansible"><a href="#configure-ansible"><span class="header-section-number">3</span> Configure ansible</a></h1> |
|---|
| 51 | <pre><code>sudo editor `/etc/ansible/ansible.cfg` and set:</code></pre> |
|---|
| 52 | <p>Make the following changes to the file:</p> |
|---|
| 53 | <pre><code>hostfile = ./hosts.local |
|---|
| 54 | ... |
|---|
| 55 | host_key_checking = False |
|---|
| 56 | ... |
|---|
| 57 | nocows = 1</code></pre> |
|---|
| 58 | <p>Finally, in your checkout's ansible directory, copy <code>hosts.sample</code> to <code>hosts.local</code></p> |
|---|
| 59 | <pre><code>cd |
|---|
| 60 | cd workshop-kit/ansible |
|---|
| 61 | cp hosts.sample hosts.local</code></pre> |
|---|
| 62 | <h1 id="first-run-network-reconfiguration"><a href="#first-run-network-reconfiguration"><span class="header-section-number">4</span> First run: network reconfiguration</a></h1> |
|---|
| 63 | <p>Still inside the ansible directory, run the following commands:</p> |
|---|
| 64 | <pre><code>sudo ansible-playbook networking.yml --check --diff # dummy run |
|---|
| 65 | sudo ansible-playbook networking.yml # live run</code></pre> |
|---|
| 66 | <p>With the <code>--check</code> flag it will show you what it is going to change; without the <code>--check</code> flag it will actually perform the changes. Try both.</p> |
|---|
| 67 | <p>The playbook is <em>idempotent</em>. This means it is safe to run it repeatedly; anything which is already in the correct state will not be changed. Feel free to run it again.</p> |
|---|
| 68 | <p>After the live run, have a look at the following files:</p> |
|---|
| 69 | <ul> |
|---|
| 70 | <li>/etc/hostname</li> |
|---|
| 71 | <li>/etc/hosts</li> |
|---|
| 72 | <li>/etc/network/interfaces</li> |
|---|
| 73 | <li>/etc/iptables/rules.v4</li> |
|---|
| 74 | </ul> |
|---|
| 75 | <p>It should have created a more complex configuration with a bridge interfaces for the LAN and WAN connections (br-lan contains eth0, br-wan contains eth1), an IP alias on 10.10.0.254, and NAT rules.</p> |
|---|
| 76 | <p>If you are happy with this configuration, reboot your server to activate the new interfaces.</p> |
|---|
| 77 | <pre><code>sudo shutdown -r now</code></pre> |
|---|
| 78 | <p>You should not need to re-run <code>networking.yml</code> again unless you want ansible to reconfigure your network.</p> |
|---|
| 79 | <h2 id="how-does-it-work"><a href="#how-does-it-work"><span class="header-section-number">4.1</span> How does it work?</a></h2> |
|---|
| 80 | <p>Have a look at the playbook:</p> |
|---|
| 81 | <pre><code>cd workshop-kit/ansible |
|---|
| 82 | cat networking.yml</code></pre> |
|---|
| 83 | <p>Notice how it contains:</p> |
|---|
| 84 | <ul> |
|---|
| 85 | <li>The host(s) or group(s) on which to run this playbook</li> |
|---|
| 86 | <li>What tasks or roles to apply</li> |
|---|
| 87 | <li>Tags, to allow parts of the playbook to be run selectively</li> |
|---|
| 88 | </ul> |
|---|
| 89 | <p>Have a look at the tasks and handlers contained under each role. Handlers are extra actions which are triggered at the end of the run if a task has changed something.</p> |
|---|
| 90 | <pre><code>cat roles/update_cache/tasks/main.yml |
|---|
| 91 | cat roles/ansible_base/tasks/main.yml |
|---|
| 92 | cat roles/networking_ubuntu/tasks/main.yml |
|---|
| 93 | cat roles/networking_ubuntu/handlers/main.yml |
|---|
| 94 | cat roles/networking_ubuntu/templates/hostname |
|---|
| 95 | cat roles/gateway_ubuntu/tasks/main.yml |
|---|
| 96 | cat roles/gateway_ubuntu/handlers/main.yml</code></pre> |
|---|
| 97 | <p>Some of these roles and templates are quite complex - don't worry about the details.</p> |
|---|
| 98 | <p>There are also variables which are set per host and group. You can find these in the inventory (hosts) and in files under host_vars/ and group_vars/</p> |
|---|
| 99 | <pre><code>cat hosts.local |
|---|
| 100 | cat host_vars/s1.ws.nsrc.org |
|---|
| 101 | cat group_vars/vm_servers |
|---|
| 102 | cat group_vars/all</code></pre> |
|---|
| 103 | <p>In particular, notice that there are variables in <code>host_vars/s1.ws.nsrc.org</code> which are used by the interfaces template:</p> |
|---|
| 104 | <pre><code>gateway_wan_interface: br-wan |
|---|
| 105 | interfaces: |
|---|
| 106 | br-lan: |
|---|
| 107 | bridge_ports: [eth0,tap11,tap12,tap13,tap14,tap15,tap16,tap17,tap18,tap19] |
|---|
| 108 | address: 10.10.0.241 |
|---|
| 109 | aliases: [10.10.0.254] |
|---|
| 110 | br-wan: |
|---|
| 111 | bridge_ports: [eth1] |
|---|
| 112 | address: dhcp</code></pre> |
|---|
| 113 | <p>If you change these, you can generate a new <code>/etc/network/interfaces</code> with different interfaces.</p> |
|---|
| 114 | <h1 id="second-run-platform-configuration"><a href="#second-run-platform-configuration"><span class="header-section-number">5</span> Second run: platform configuration</a></h1> |
|---|
| 115 | <pre><code>sudo ansible-playbook vm_servers.yml -t platform</code></pre> |
|---|
| 116 | <p>This installs a few basic packages. If your machine is a Mac Mini then it will install packages specific to that platform, e.g. macfanctld.</p> |
|---|
| 117 | <p><code>-t platform</code> means only to run those tasks labelled with tag "platform".</p> |
|---|
| 118 | <p>Some steps may take a a while to complete. If you see this step hang for a very long time:</p> |
|---|
| 119 | <p>TASK: [install macmini packages] **********************************************</p> |
|---|
| 120 | <p>You may want to press "ctrl-c" and run the command again. It's possible there is a dialogue we have not accounted for that has hung the process.</p> |
|---|
| 121 | <h1 id="third-run-full-configuration"><a href="#third-run-full-configuration"><span class="header-section-number">6</span> Third run: full configuration</a></h1> |
|---|
| 122 | <p>Now run the vm_servers.yml playbook again, but without restricting to the platform tag.</p> |
|---|
| 123 | <pre><code>sudo ansible-playbook vm_servers.yml</code></pre> |
|---|
| 124 | <p>This will run through a full set of configuration including:</p> |
|---|
| 125 | <ul> |
|---|
| 126 | <li>dns server</li> |
|---|
| 127 | <li>ntp server</li> |
|---|
| 128 | <li>snmp agent</li> |
|---|
| 129 | <li>apt-cacher</li> |
|---|
| 130 | <li>dhcp server</li> |
|---|
| 131 | <li>kvm</li> |
|---|
| 132 | <li>vmbuilder</li> |
|---|
| 133 | <li>dynamips</li> |
|---|
| 134 | </ul> |
|---|
| 135 | <p>This may take a fair amount of time to complete.</p> |
|---|
| 136 | <p>At this point you should have functioning DHCP on your LAN network. If you had configured a static IP on your laptop, you no longer need it.</p> |
|---|
| 137 | <p>You can look around and see how your MacMini has changed. For instance, you are now running an snmp server:</p> |
|---|
| 138 | <pre><code>snmpwalk -v2c -c NetManage localhost</code></pre> |
|---|
| 139 | <p>DNS for your private network that you will be using has been configured:</p> |
|---|
| 140 | <pre><code>dig pc10.ws.nsrc.org |
|---|
| 141 | dig sw.ws.nsrc.org</code></pre> |
|---|
| 142 | <p>You might to consider looking at current running processes, use netstat to see your current routes or open ports, typing ifconig to see all your interfaces, etc... to get a feel for your new MacMini environment.</p> |
|---|
| 143 | <p>Note that you can now use your wireless access point to connect to your MacMini. On your laptop connect to the SSID for your group (KITX-24 or KITX-5 where X={1..6}). You will receive an address on the 10.10.0.0/24 network with a gateway of 10.10.0.254, which is your MacMini, a DNS server of 10.10.0.241 (again, your MacMini) and you will have full access to the public internet.</p> |
|---|
| 144 | <h1 id="appendix"><a href="#appendix"><span class="header-section-number">7</span> Appendix</a></h1> |
|---|
| 145 | <h2 id="pointing-your-apt-to-your-local-apt-cacher-instance"><a href="#pointing-your-apt-to-your-local-apt-cacher-instance"><span class="header-section-number">7.1</span> Pointing your apt to your local apt-cacher instance</a></h2> |
|---|
| 146 | <p>Your box is now acting as a cache for installation of software using apt and is available for use for any machine on your private network (10.0.0.0/8). However, we have not set your own MacMini to use the cache that it is running. You can do this if you wish, but remember, if you must troubleshoot issues with apt, then you will probably need to disable this by removing/moving the file we will create below.</p> |
|---|
| 147 | <p>If you wish to point to your local apt-cacher program do the following:</p> |
|---|
| 148 | <pre><code>sudo editor /etc/apt/apt.conf.d/01proxy</code></pre> |
|---|
| 149 | <p>and add the line:</p> |
|---|
| 150 | <pre><code>Acquire::http::Proxy "http://127.0.0.1:3142";</code></pre> |
|---|
| 151 | <p>Now update your local apt database:</p> |
|---|
| 152 | <pre><code>sudo apt update</code></pre> |
|---|
| 153 | <p>The next time you use apt to install a package it will first see if it is available locally and use that copy if it's available. Otherwise, the package will still be downloaded over the network, but it will now be available for all other users who may wish to install the software.</p> |
|---|
| 154 | <h2 id="using-git"><a href="#using-git"><span class="header-section-number">7.2</span> Using git</a></h2> |
|---|
| 155 | <p>Detailed instructions for using git with ssh and configuring it for use for interactive work flow.</p> |
|---|
| 156 | <p>This assumes you have an account on git.nsrc.org and your ssh public key has been installed there.</p> |
|---|
| 157 | <pre><code>cd |
|---|
| 158 | git clone ssh://YOURUSERNAME@git.nsrc.org/usr/local/repositories/workshop-kit.git |
|---|
| 159 | cd workshop-kit</code></pre> |
|---|
| 160 | <p>If authentication is rejected, you should NOT copy your ssh private key onto your workshop server! Rather you should:</p> |
|---|
| 161 | <ol style="list-style-type: decimal"> |
|---|
| 162 | <li>Disconnect your ssh session</li> |
|---|
| 163 | <li>Log back in using ssh and agent forwarding |
|---|
| 164 | <ul> |
|---|
| 165 | <li>For Linux and OSX: |
|---|
| 166 | <ul> |
|---|
| 167 | <li>ssh-add |
|---|
| 168 | <ul> |
|---|
| 169 | <li>enter your passphrase when prompted</li> |
|---|
| 170 | </ul></li> |
|---|
| 171 | <li>ssh -oForwardAgent=yes nsrc@x.x.x.x</li> |
|---|
| 172 | </ul></li> |
|---|
| 173 | <li>For Windows/putty: |
|---|
| 174 | <ul> |
|---|
| 175 | <li>run pageant</li> |
|---|
| 176 | <li>point it to your private key and enter your passphrase</li> |
|---|
| 177 | <li>connect with agent forwarding enabled</li> |
|---|
| 178 | </ul></li> |
|---|
| 179 | </ul></li> |
|---|
| 180 | </ol> |
|---|
| 181 | <h3 id="configure-git"><a href="#configure-git"><span class="header-section-number">7.2.1</span> Configure git</a></h3> |
|---|
| 182 | <p>Create a file <code>~/.gitconfig</code> containing the following. This ensures that any commits you make are labelled with your correct details.</p> |
|---|
| 183 | <pre><code>[user] |
|---|
| 184 | name = Your Fullname |
|---|
| 185 | email = yourname@yourdomain |
|---|
| 186 | [core] |
|---|
| 187 | excludesfile = ~/.gitignore |
|---|
| 188 | #editor = /usr/bin/joe << or whatever you prefer |
|---|
| 189 | [push] |
|---|
| 190 | default = tracking</code></pre> |
|---|
| 191 | <p>And create <code>~/.gitignore</code> as follows: this is to minimise the junk which is picked up.</p> |
|---|
| 192 | <pre><code>*~</code></pre> |
|---|
| 193 | <h1 id="obtaining-workshop-kit-files-with-tarballs"><a href="#obtaining-workshop-kit-files-with-tarballs"><span class="header-section-number">8</span> Obtaining workshop kit files with tarballs</a></h1> |
|---|
| 194 | <h2 id="from-a-tarball"><a href="#from-a-tarball"><span class="header-section-number">8.1</span> From a tarball</a></h2> |
|---|
| 195 | <p>Alternatively, you may be given a tarball or zipfile containing a snapshot of the repository. Download it using wget, and extract it as appropriate:</p> |
|---|
| 196 | <pre><code>cd |
|---|
| 197 | wget http://...../workshop-kit.tgz |
|---|
| 198 | tar -xvzf workshop-kit.tgz |
|---|
| 199 | |
|---|
| 200 | or: |
|---|
| 201 | wget http://...../workshop-kit.zip |
|---|
| 202 | unzip workshop-kit.zip</code></pre> |
|---|
| 203 | <p>Either way, you should have a directory called "workshop-kit" which you can cd into.</p> |
|---|
| 204 | </body> |
|---|
| 205 | </html> |
|---|
