Changes between Version 1 and Version 2 of GpoLab/MyplcNodeDataplaneInterfaces


Ignore:
Timestamp:
04/22/11 14:27:47 (13 years ago)
Author:
chaos@bbn.com
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • GpoLab/MyplcNodeDataplaneInterfaces

    v1 v2  
    44
    55This page discusses how to configure secondary interfaces on MyPLC-controlled PlanetLab nodes.
     6
     7== Secondary interface IP configuration using plifconfig ==
     8
     9=== Variables ===
     10
     11<version>: the target plifconfig version
     12
     13=== Set Up the Environment for VLAN Interfaces ===
     14
     15==== Obtain Scripts and Patches ====
     16
     17The latest plifconfig tarball can be obtained from `gpo-infra@geni.net`.  Copy the tarball onto your MyPLC machine, and unpackage it in your home directory:
     18{{{
     19cd ~
     20tar xvzf /path/to/plifconfig-<version>.tar.gz
     21}}}
     22
     23''Instructions below assume that you downloaded the package to your home directory on your MyPLC machine.''
     24
     25==== Add VLAN Tagtype to !PlanetLab Database on MyPLC Machine ====
     26
     27To create VLAN subinterfaces, you need to add a new tag type to your !PlanetLab database.
     28
     29 * Run the `add_vlan_tagtype_to_plc_db` script:
     30{{{
     31sudo ~/plifconfig-<version>/myplc/add_vlan_tagtype_to_plc_db
     32}}}
     33
     34 * Confirm tagtype was added:
     35{{{
     36sudo ~/plifconfig-<version>/myplc/add_vlan_tagtype_to_plc_db -- -n
     37echo $?
     38}}}
     39
     40If '''1''' is printed out by the echo command then the VLAN tagtype was successfully added to the !PlanetLab database.
     41
     42==== Apply the Patch on All Nodes ====
     43
     44In order to create VLAN interfaces on a node, you need to patch your plnet.py file.  This will need to be done on each !PlanetLab node associated with your MyPLC.
     45 * Copy the patch file to your nodes:
     46{{{
     47scp ~/plifconfig-<version>/nodes/plnet.patch root@<fqdn_of_node>:~/
     48}}}
     49
     50 * Login to the node as root
     51 * Create a copy of the original plnet.py, and keep it in your home directory for safe keeping:
     52{{{
     53cd /usr/lib/python2.5/site-packages/
     54cp plnet.py ~/plnet.py.orig
     55}}}
     56
     57 * Still on the node as root, apply the patch:
     58{{{
     59cd /usr/lib/python2.5/site-packages/
     60patch < ~/plnet.patch
     61}}}
     62
     63 * Restart !NodeManager on the node:
     64{{{
     65service nm restart
     66}}}
     67
     68==== What if the patch didn't work? ====
     69
     70The expected original file and patched file are included in `plifconfig-<version>/nodes/plnet/` for you to reference.  If the patch did not work please let us know at gpo-infra@geni.net.
     71
     72=== The `plifconfig` Tool ===
     73
     74==== Purpose of the `plifconfig` Tool ====
     75
     76plifconfig is a management tool for network interfaces on !PlanetLab nodes.[[BR]]
     77The tool can be used to be add new interfaces to a node, remove interfaces [[BR]]
     78from a node, or show information about interfaces on a given node.
     79
     80==== Setup the `plifconfig` Tool ====
     81
     82 * Setup the plifconfig.py library on your MyPLC machine:
     83{{{
     84cd ~/plifconfig-<version>/myplc/
     85sudo cp plifconfig.py /usr/local/lib/
     86sudo chown root /usr/local/lib/plifconfig.py
     87sudo chmod 444 /usr/local/lib/plifconfig.py
     88}}}
     89
     90 * Setup the plifconfig wrapper script on your MyPLC machine:
     91{{{
     92cd ~/plifconfig-<version>/myplc/
     93sudo cp plifconfig /usr/local/sbin/
     94sudo chown root /usr/local/sbin/plifconfig
     95sudo chmod 544 /usr/local/sbin/plifconfig
     96}}}
     97
     98==== Using the `plifconfig` Tool ====
     99
     100`plifconfig` currently supports 4 basic subcommands:
     101 * add: add an interface with statically defined values (DHCP not yet supported)
     102 * del: delete an interface
     103 * show: show detailed information about an interface
     104 * list: list all interfaces
     105
     106The tool has a help option (-h or --help) for plifconfig and all of its subcommands for more information on usage.
     107{{{
     108[you@myplc] $ sudo plifconfig -h
     109[you@myplc] $ sudo plifconfig add -h
     110[you@myplc] $ sudo plifconfig del -h
     111[you@myplc] $ sudo plifconfig show -h
     112[you@myplc] $ sudo plifconfig list -h
     113}}}
     114
     115==== Typical `plifconfig` Workflows ====
     116
     117===== Adding an Interface to a Node =====
     118
     119If you have more than one NIC attached to your host, you will need to add it to the !PlanetLab database on your MyPLC machine for it to be usable.  In the example below, I will add `eth1` to `node2.fqdn.com`.  Note that you can add interfaces without IP addresses by specifying an IP address of `0.0.0.0` and a netmask of `255.255.255.255`.
     120
     121{{{
     122[you@myplc] $ sudo plifconfig list
     123
     124Node: node1.fqdn.com
     125        IP:  125.125.125.88 HWaddr: ab:12:cd:34:ef:77 Device: eth0
     126        IP:         1.2.3.5 HWaddr: ab:12:cd:34:ef:56 Device: eth1
     127        IP:        10.2.3.3 HWaddr:                   Device: eth1:1234
     128
     129Node: node2.fqdn.com
     130        IP:   125.125.125.3 HWaddr: ab:12:cd:34:ef:11 Device: eth0       
     131
     132[you@myplc] $ sudo plifconfig add -n node2.fqdn.com -i 10.2.3.6 -m 255.255.255.128 -d eth1 -g 10.2.3.1 --mac ab:12:cd:34:ef:99
     133
     134Interface successfully created
     135
     136[you@myplc] $ sudo plifconfig list
     137
     138Node: node1.fqdn.com
     139        IP:  125.125.125.88 HWaddr: ab:12:cd:34:ef:77 Device: eth0
     140        IP:         1.2.3.5 HWaddr: ab:12:cd:34:ef:56 Device: eth1
     141        IP:        10.2.3.3 HWaddr:                   Device: eth1:1234
     142
     143Node: node2.fqdn.com
     144        IP:   125.125.125.3 HWaddr: ab:12:cd:34:ef:11 Device: eth0
     145        IP:        10.2.3.6 HWaddr: ab:12:cd:34:ef:99 Device: eth1
     146}}}
     147
     148===== Adding an Alias or VLAN Interface to a Node: =====
     149
     150You can create an alias or a VLAN interface in the same way that you create normal interfaces.  The only difference is that you must pass a device name and a value for the VLAN id or the alias.  The device must exist in the !PlanetLab database in order to create the alias or VLAN interface. 
     151
     152====== Adding a VLAN Interface to a Node ======
     153
     154{{{
     155[you@myplc] $ sudo plifconfig list
     156
     157Node: node1.fqdn.com
     158        IP:  125.125.125.88 HWaddr: ab:12:cd:34:ef:77 Device: eth0
     159        IP:         1.2.3.5 HWaddr: ab:12:cd:34:ef:56 Device: eth1
     160        IP:        10.2.3.3 HWaddr:                   Device: eth1:1234
     161
     162Node: node2.fqdn.com
     163        IP:   125.125.125.3 HWaddr: ab:12:cd:34:ef:11 Device: eth0
     164        IP:        10.2.3.6 HWaddr: ab:12:cd:34:ef:99 Device: eth1       
     165
     166[you@myplc] $ sudo plifconfig add -n node2.fqdn.com -i 10.2.4.7 -m 255.255.255.128 -d eth1 --vlan 123 -g 10.2.4.1
     167
     168Interface successfully created
     169
     170[you@myplc] $ sudo plifconfig list
     171
     172Node: node1.fqdn.com
     173        IP:  125.125.125.88 HWaddr: ab:12:cd:34:ef:77 Device: eth0
     174        IP:         1.2.3.5 HWaddr: ab:12:cd:34:ef:56 Device: eth1
     175        IP:        10.2.3.3 HWaddr:                   Device: eth1:1234
     176
     177Node: node2.fqdn.com
     178        IP:   125.125.125.3 HWaddr: ab:12:cd:34:ef:11 Device: eth0   
     179        IP:        10.2.3.6 HWaddr: ab:12:cd:34:ef:99 Device: eth1
     180        IP:        10.2.4.7 HWaddr:                   Device: eth1.123
     181}}}
     182
     183====== Adding an Alias to a Node ======
     184
     185{{{
     186[you@myplc] $ sudo plifconfig list
     187
     188Node: node1.fqdn.com
     189        IP:  125.125.125.88 HWaddr: ab:12:cd:34:ef:77 Device: eth0
     190        IP:         1.2.3.5 HWaddr: ab:12:cd:34:ef:56 Device: eth1
     191        IP:        10.2.3.3 HWaddr:                   Device: eth1:1234
     192
     193Node: node2.fqdn.com
     194        IP:   125.125.125.3 HWaddr: ab:12:cd:34:ef:11 Device: eth0
     195        IP:        10.2.3.6 HWaddr: ab:12:cd:34:ef:99 Device: eth1
     196        IP:        10.2.4.7 HWaddr:                   Device: eth1.123     
     197
     198[you@myplc] $ sudo plifconfig add -n node2.fqdn.com -i 10.2.4.8 -m 255.255.255.128 -d eth1 --alias 123 -g 10.2.4.1
     199
     200Interface successfully created
     201
     202[you@myplc] $ sudo plifconfig list
     203
     204Node: node1.fqdn.com
     205        IP:  125.125.125.88 HWaddr: ab:12:cd:34:ef:77 Device: eth0
     206        IP:         1.2.3.5 HWaddr: ab:12:cd:34:ef:56 Device: eth1
     207        IP:        10.2.3.3 HWaddr:                   Device: eth1:1234
     208
     209Node: node2.fqdn.com
     210        IP:   125.125.125.3 HWaddr: ab:12:cd:34:ef:11 Device: eth0   
     211        IP:        10.2.3.6 HWaddr: ab:12:cd:34:ef:99 Device: eth1
     212        IP:        10.2.4.7 HWaddr:                   Device: eth1.123
     213        IP:        10.2.4.8 HWaddr:                   Device: eth1:123
     214}}}
     215
     216====== Adding a Alias of a VLAN Interface to a Node ======
     217
     218{{{
     219[you@myplc] $ sudo plifconfig list
     220
     221Node: node1.fqdn.com
     222        IP:  125.125.125.88 HWaddr: ab:12:cd:34:ef:77 Device: eth0
     223        IP:         1.2.3.5 HWaddr: ab:12:cd:34:ef:56 Device: eth1
     224        IP:        10.2.3.3 HWaddr:                   Device: eth1:1234
     225
     226Node: node2.fqdn.com
     227        IP:   125.125.125.3 HWaddr: ab:12:cd:34:ef:11 Device: eth0
     228        IP:        10.2.3.6 HWaddr: ab:12:cd:34:ef:99 Device: eth1
     229        IP:        10.2.4.7 HWaddr:                   Device: eth1.123
     230        IP:        10.2.4.8 HWaddr:                   Device: eth1:123   
     231
     232[you@myplc] $ sudo plifconfig add -n node2.fqdn.com -i 10.2.4.9 -m 255.255.255.128 -d eth1 --vlan 123 --alias 123 -g 10.2.4.1
     233
     234Interface successfully created
     235
     236[you@myplc] $ sudo plifconfig list
     237
     238Node: node1.fqdn.com
     239        IP:  125.125.125.88 HWaddr: ab:12:cd:34:ef:77 Device: eth0
     240        IP:         1.2.3.5 HWaddr: ab:12:cd:34:ef:56 Device: eth1
     241        IP:        10.2.3.3 HWaddr:                   Device: eth1:1234
     242
     243Node: node2.fqdn.com
     244        IP:   125.125.125.3 HWaddr: ab:12:cd:34:ef:11 Device: eth0   
     245        IP:        10.2.3.6 HWaddr: ab:12:cd:34:ef:99 Device: eth1
     246        IP:        10.2.4.7 HWaddr:                   Device: eth1.123
     247        IP:        10.2.4.8 HWaddr:                   Device: eth1:123
     248        IP:        10.2.4.9 HWaddr:                   Device: eth1.123:123
     249}}}
     250
     251===== Viewing Interface Details =====
     252
     253To look up more information about a specific node, you can use the `show` subcommand.  All of this information can also be found on the node or on the web interface, but the `show` subcommand is useful for quickly debugging issues from a central location.  Note that when querying by device, you must specify the full set of {device, vlan, alias} of the device.  For example, to see information on eth1, specify {{{ -d eth1 }}}.  To see information on eth1.123:3, specify {{{ -d eth1 --vlan 123 --alias 3 }}}.  To see information on eth1:3, specify {{{ -d eth1 --alias 3 }}}.
     254
     255{{{
     256[you@myplc] $ sudo plifconfig show -n node1.fqdn.com -d eth1 --alias 1234
     257Interface details for query: node = node1.fqdn.com, device = eth1:1234
     258Node: node1.fqdn.com
     259Device: eth1:1234
     260HWaddr:
     261Is Primary? False
     262Bandwidth limit: None
     263IP Version: ipv4
     264Method: static
     265
     266IP:           10.2.3.3
     267Bcast:       10.2.3.63 Mask: 255.255.255.192
     268NetID:        10.2.3.0 GW:          10.2.3.1
     269DNS1:  125.125.125.244 DNS2:
     270}}}
     271
     272===== Deleting Interfaces =====
     273
     274If you need to remove an interface you can use the `del` subcommand.  Note that when querying by device, you must specify the full set of {device, vlan, alias} of the device.  For example, to see information on eth1, specify {{{ -d eth1 }}}.  To see information on eth1.123:3, specify {{{ -d eth1 --vlan 123 --alias 3 }}}.  To see information on eth1:3, specify {{{ -d eth1 --alias 3 }}}.
     275
     276{{{
     277[you@myplc] $ sudo plifconfig list
     278
     279Node: node1.fqdn.com
     280        IP:  125.125.125.88 HWaddr: ab:12:cd:34:ef:77 Device: eth0
     281        IP:         1.2.3.5 HWaddr: ab:12:cd:34:ef:56 Device: eth1
     282        IP:        10.2.3.3 HWaddr:                   Device: eth1:1234
     283
     284Node: node2.fqdn.com
     285        IP:   125.125.125.3 HWaddr: ab:12:cd:34:ef:11 Device: eth0
     286        IP:        10.2.3.6 HWaddr: ab:12:cd:34:ef:99 Device: eth1
     287        IP:        10.2.4.7 HWaddr:                   Device: eth1.123
     288
     289[you@myplc] $ sudo plifconfig del -n node1.fqdn.com -d eth1 --alias 1234
     290
     291Interface successfully deleted
     292
     293[you@myplc] $ sudo plifconfig list
     294
     295Node: node1.fqdn.com
     296        IP:  125.125.125.88 HWaddr: ab:12:cd:34:ef:77 Device: eth0
     297        IP:         1.2.3.5 HWaddr: ab:12:cd:34:ef:56 Device: eth1
     298
     299Node: node2.fqdn.com
     300        IP:   125.125.125.3 HWaddr: ab:12:cd:34:ef:11 Device: eth0
     301        IP:        10.2.3.6 HWaddr: ab:12:cd:34:ef:99 Device: eth1
     302        IP:        10.2.4.7 HWaddr:                   Device: eth1.123
     303}}}
     304
     305==== `plifconfig` Best Practices ====
     306
     307 * '''Always fully specify the interface you are operating on.''' There are three `plifconfig` flags, `-d`, `--vlan`, and `--alias`, which are used to uniquely identify a given device and subinterface.  While it may be possible for the OS to fill in the `-d` flag correctly, you should always specify it when you invoke `plifconfig` to ensure that you are operating on the correct device.  Whenever you are viewing or modifying information for a subinterface, always specify that subinterface fully.
     308
     309 * '''Use MAC addresses when defining physical interfaces.''' Whenever you configure a physical interface (e.g. `eth1`) in `plifconfig`, specify the MAC address.  This will ensure that device names do not change across node reboots.  However, '''do not specify MAC addresses when defining virtual subinterfaces''' (whether VLAN- or alias-based) --- a [#plifconfigKnownBugs known bug] causes trouble when the same MAC address is used on multiple defined interfaces.
     310
     311 * '''Be careful when adding or deleting interfaces.'''  `plifconfig` does not ask for confirmation when adding or deleting interfaces.  For example, `plifconfig` won't prevent you from deleting your primary interface.  If you do this, you might not be able to change the interfaces on the node without doing a ''physical reboot'' of the node.
     312
     313 * '''Manage interfaces from the MyPLC machine, not from the !PlanetLab node.'''  If you try to manage interfaces on the node using traditional tools like `ifconfig` and `ifcfg-ethX` startup scripts, it will clash with the !PlanetLab way of creating interfaces.  MyPLC wants to manage the interfaces actively, so use either `plifconfig` or the MyPLC web interface.
     314
     315 * '''Use the fast sliver creation change described [http://groups.geni.net/geni/wiki/GpoLab/MyplcReferenceImplementation#SetupFastSliverCreation here].'''  !PlanetLab nodes will create new slivers and new interfaces at the same time; thus, if you are only creating slivers every 15 minutes, then you will only be able to add or delete interfaces every 15 minutes.
     316
     317==== `plifconfig` Known Bugs ====
     318
     319 * When using `plifconfig`, you can only specify a mac address once when adding interfaces.  Although aliases and VLAN interfaces share the same mac address as their associated ethX parent interface, if you specify that mac address for all of these interfaces then unexpected behavior can occur on the node.  For the time being, it is recommended to specify a mac address for the ethX interface, and to not specify mac addresses for VLAN interfaces or aliases.
     320
     321 * Currently, `plifconfig` allows you to delete an interface that has subinterfaces attached to it.  For example, if I have eth1, eth1.123, and eth1:3, `plifconfig` does not prevent you from deleting eth1.  Similarly, plifconfig does not prevent you from adding a subinterface to a physical interface that is not already in the database.
     322
     323==== `plifconfig` FAQ ====
     324
     325 1. Q: Can I create multiple interfaces with the same IP address?[[BR]]
     326 '''A: Yes, but not on the same node.  The only exception to this rule is having multiple interfaces with an IP address of 0.0.0.0.'''
     327
     328 2. Q: Interfaces are not showing up inside of my slices.  How can I fix that?[[BR]]
     329 '''A: One suggested fix which may or may not apply to you is listed [http://groups.geni.net/geni/wiki/GpoLab/MyplcReferenceImplementation#ImportantNotesonPlanetLabNodeInterfaces here].[[BR]]
     330   Another suggestion is outlined below:'''
     331  * Log into your MyPLC's web interface
     332  * Click "Slices" in the left-hand navigation bar
     333  * Click on the name of the slice of your choice in the table on the slices page
     334   * On the page for your slice:
     335   * Expand the "tags" view
     336   * Select "ip_addresses" from the "Choose Tag" dropdown
     337   * Enter 0.0.0.0 into the text box as the value of the tag
     338   * Make sure either "All Nodes" or your specific node is selected to apply the tag to
     339   * Hit the "Set Tag" button to confirm
     340  * Log into the root context of your !PlanetLab node and run:
     341{{{
     342service nm restart
     343}}}
     344  * Log into the slice and confirm that the interfaces are visible
     345
     346 3. Q: How do I modify an interface that I have already added?[[BR]]
     347 '''A: There is currently no way to do this through `plifconfig` other than deleting and adding the interface again.  You can still modify the interface's properties through the "interface" and "interface tags" pages of the MyPLC web interface.'''
     348
     349 4. Q: Can I set the bandwidth limit of an interface through `plifconfig`?[[BR]]
     350 '''A: Not currently.  Please contact gpo-infra@geni.net if this feature would be useful in your environment.'''
     351
     352 5. Q: Does `plifconfig` support creation of DHCP interfaces?[[BR]]
     353 '''A: Not currently.  Please contact gpo-infra@geni.net if this feature would be useful in your environment.'''
     354
     355 6. Q: Does `plifconfig` support creation of IPv6 interfaces?[[BR]]
     356 '''A: Not currently.  Please contact gpo-infra@geni.net if this feature would be useful in your environment.'''
     357
    6358
    7359== Interface numbering gotchas ==