To run DevStack for the stable Folsom branch on an instance:

1. Boot an instance from the Dashboard or the nova command-line interface (CLI) with the following parameters.

   • Name: devstack

   • Image: Ubuntu 12.04 LTS

   • Memory Size: 4 GB RAM (you could probably get away with 2 GB)

   • Disk Size: minimum 5 GB

   If you are using the nova client, specify --flavor 6 on the nova boot command to get adequate memory and disk sizes.

2. If your images have only a root user, you must create a “stack” user. Otherwise you run into permission issues with screen if you let stack.sh create the “stack” user for you. If your images already have a user other than root, you can skip this step.

   1. ssh root@<IP Address>

   2. adduser --gecos "" stack

   3. Enter a new password at the prompt.

   4. adduser stack sudo

   5. grep -q "^#includedir.*/etc/sudoers.d" /etc/sudoers || echo "#includedir /etc/sudoers.d" >> /etc/sudoers

   6. ( umask 226 && echo "stack ALL=(ALL) NOPASSWD:ALL" > /etc/sudoers.d/50_stack_sh )

   7. exit

3. Now login as the stack user and set up DevStack.

   1. ssh stack@<IP address>

   2. At the prompt, enter the password that you created for the stack user. 

   3. sudo apt-get -y update

   4. sudo apt-get -y install git

   5. git clone https://github.com/openstack-dev/devstack.git -b stable/folsom devstack/

   6. cd devstack

   7. vim localrc

      • For Swift only, used in the Middleware Example, see the example [1] Swift only localrc below

      • For all other projects, used in the Nova Scheduler Example, see the example [2] All other projects localrc below

   8. ./stack.sh

   9. screen -r stack 

   • The stack.sh script takes a while to run. Perhaps take this opportunity to join the OpenStack foundation (http://www.openstack.org/join/).

   • When you run stack.sh, you might see an error message that reads “ERROR: at least one RPC back-end must be enabled”. Don’t worry about it; swift and keystone do not need an RPC (AMQP) back-end. You can also ignore any ImportErrors.

   • Screen is a useful program for viewing many related services at once. For more information, see GNU screen quick reference. (http://aperiodic.net/screen/quick_reference)

This example is for illustrative purposes only. It should not be used as a container IP whitelist solution without further development and extensive security testing.

To create the middleware and plug it in through Paste configuration:

1. All of the code for OpenStack lives in /opt/stack. Go to the swift directory in the shell screen and edit your middleware module.

   1. cd /opt/stack/swift

   2. vim swift/common/middleware/ip_whitelist.py

2. Copy in the following code. When you’re done, save and close the file.

   # Licensed under the Apache License, Version 2.0 (the "License");
   # you may not use this file except in compliance with the License.
   # You may obtain a copy of the License at
   #
                        
   #    http://www.apache.org/licenses/LICENSE-2.0
   #
   # Unless required by applicable law or agreed to in writing, software
   # distributed under the License is distributed on an "AS IS" BASIS,
   # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
   # implied.
   # See the License for the specific language governing permissions and
   # limitations under the License.
   import socket
    
   from swift.common.utils import get_logger
   from swift.proxy.controllers.base import get_container_info
   from swift.common.swob import Request, Response
    
   class IPWhitelistMiddleware(object):
       """
       IP Whitelist Middleware
   
       Middleware that allows access to a container from only a set of IP
       addresses as determined by the container's metadata items that start
       with the prefix 'allow'. E.G. allow-dev=192.168.0.20
       """
   
       def __init__(self, app, conf, logger=None):
           self.app = app
   
           if logger:
               self.logger = logger
           else:
               self.logger = get_logger(conf, log_route='ip_whitelist')
   
           self.deny_message = conf.get('deny_message', "IP Denied")
           self.local_ip = socket.gethostbyname(socket.gethostname())
   
       def __call__(self, env, start_response):
           """
           WSGI entry point.
           Wraps env in swob.Request object and passes it down.
   
           :param env: WSGI environment dictionary
           :param start_response: WSGI callable
           """
           req = Request(env)
   
           try:
               version, account, container, obj = req.split_path(1, 4, True)
           except ValueError:
               return self.app(env, start_response)
   
           container_info = get_container_info(
               req.environ, self.app, swift_source='IPWhitelistMiddleware')
   
           remote_ip = env['REMOTE_ADDR']
           self.logger.debug(_("Remote IP: %(remote_ip)s"),
                             {'remote_ip': remote_ip})
   
           meta = container_info['meta']
           allow = {k:v for k,v in meta.iteritems() if k.startswith('allow')}
           allow_ips = set(allow.values())
           allow_ips.add(self.local_ip)
           self.logger.debug(_("Allow IPs: %(allow_ips)s"),
                             {'allow_ips': allow_ips})
   
           if remote_ip in allow_ips:
               return self.app(env, start_response)
           else:
               self.logger.debug(
                   _("IP %(remote_ip)s denied access to Account=%(account)s "
                     "Container=%(container)s. Not in %(allow_ips)s"), locals())
               return Response(
                   status=403,
                   body=self.deny_message,
                   request=req)(env, start_response)
   
   
   def filter_factory(global_conf, **local_conf):
       """
       paste.deploy app factory for creating WSGI proxy apps.
       """
       conf = global_conf.copy()
       conf.update(local_conf)
   
       def ip_whitelist(app):
           return IPWhitelistMiddleware(app, conf)
       return ip_whitelist
                    

   There is a lot of useful information in env and conf that you can use to decide what to do with the request. To find out more about what properties are available, you can insert the following log statement into the __init__ method

   self.logger.debug(_("conf = %(conf)s"), locals())

   and the following log statement into the __call__ method

   self.logger.debug(_("env = %(env)s"), locals())

3. To plug this middleware into the Swift pipeline you’ll need to edit one configuration file.

    vim /etc/swift/proxy-server.conf

4. Find the [filter:ratelimit] section and copy in the following configuration section.

   [filter:ip_whitelist]
   paste.filter_factory = swift.common.middleware.ip_whitelist:filter_factory
   # You can override the default log routing for this filter here:
   # set log_name = ratelimit
   # set log_facility = LOG_LOCAL0
   # set log_level = INFO
   # set log_headers = False
   # set log_address = /dev/log
   deny_message = You shall not pass!

5. Find the [pipeline:main] section and add ip_whitelist to the list like so. When you’re done, save and close the file.

   [pipeline:main]
   pipeline = catch_errors healthcheck cache ratelimit ip_whitelist authtoken keystoneauth proxy-logging proxy-server

6. Restart the Swift Proxy service to make Swift use your middleware. Start by switching to the swift screen.

   1. Press Ctrl-A followed by pressing 2, where 2 is the label of the screen. You can also press Ctrl-A followed by pressing n to go to the next screen.

   2. Press Ctrl-C to kill the service.

   3. Press Up Arrow to bring up the last command.

   4. Press Enter to run it.

7. Test your middleware with the Swift CLI. Start by switching to the shell screen and finish by switching back to the swift screen to check the log output.

   1. Press Ctrl-A followed by pressing 0

   2. cd ~/devstack

   3. source openrc

   4. swift post middleware-test

   5. Press Ctrl-A followed by pressing 2

8. Among the log statements you’ll see the lines.

   proxy-server ... IPWhitelistMiddleware
   proxy-server Remote IP: 203.0.113.68 (txn: ...)
   proxy-server Allow IPs: set(['203.0.113.68']) (txn: ...)

   The first three statements basically have to do with the fact that middleware doesn’t need to re-authenticate when it interacts with other Swift services. The last 2 statements are produced by our middleware and show that the request was sent from our DevStack instance and was allowed.

9. Test the middleware from outside of DevStack on a remote machine that has access to your DevStack instance.

   1. swift --os-auth-url=http://203.0.113.68:5000/v2.0/ --os-region-name=RegionOne --os-username=demo:demo --os-password=devstack list middleware-test

   2. Container GET failed: http://203.0.113.68:8080/v1/AUTH_.../middleware-test?format=json 403 Forbidden   You shall not pass!

10. Check the Swift log statements again and among the log statements you’ll see the lines.

    proxy-server Invalid user token - deferring reject downstream
    proxy-server Authorizing from an overriding middleware (i.e: tempurl) (txn: ...)
    proxy-server ... IPWhitelistMiddleware
    proxy-server Remote IP: 198.51.100.12 (txn: ...)
    proxy-server Allow IPs: set(['203.0.113.68']) (txn: ...)
    proxy-server IP 198.51.100.12 denied access to Account=AUTH_... Container=None. Not in set(['203.0.113.68']) (txn: ...)

    Here we can see that the request was denied because the remote IP address wasn’t in the set of allowed IPs.

11. Back on your DevStack instance add some metadata to your container to allow the request from the remote machine.

    1. Press Ctrl-A followed by pressing 0

    2. swift post --meta allow-dev:198.51.100.12 middleware-test

12. Now try the command from ??? again and it succeeds.

This example is for illustrative purposes only. It should not be used as a scheduler for Nova without further development and testing.

To create the scheduler and plug it in through configuration:

1. The code for OpenStack lives in /opt/stack so go to the nova directory and edit your scheduler module.

   1. cd /opt/stack/nova

   2. vim nova/scheduler/ip_scheduler.py

2. Copy in the following code. When you’re done, save and close the file.

   # vim: tabstop=4 shiftwidth=4 softtabstop=4
   # Copyright (c) 2013 OpenStack Foundation
   # All Rights Reserved.
   #
   #    Licensed under the Apache License, Version 2.0 (the "License"); you may
   #    not use this file except in compliance with the License. You may obtain
   #    a copy of the License at
   #
   #   http://www.apache.org/licenses/LICENSE-2.0
   #
   #    Unless required by applicable law or agreed to in writing, software
   #    distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
   #    WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
   #    License for the specific language governing permissions and limitations
   #    under the License.
   
   """
   IP Scheduler implementation
   """
   
   import random
   
   from nova import exception
   from nova.openstack.common import log as logging
   from nova import flags
   from nova.scheduler import driver
   
   FLAGS = flags.FLAGS
   LOG = logging.getLogger(__name__)
   
   
   class IPScheduler(driver.Scheduler):
       """
       Implements Scheduler as a random node selector based on
       IP address and hostname prefix.
       """
   
       def _filter_hosts(self, hosts, hostname_prefix):
           """Filter a list of hosts based on hostname prefix."""
   
           hosts = [host for host in hosts if host.startswith(hostname_prefix)]
           return hosts
   
       def _schedule(self, context, topic, request_spec, filter_properties):
           """
           Picks a host that is up at random based on
           IP address and hostname prefix.
           """
   
           elevated = context.elevated()
           hosts = self.hosts_up(elevated, topic)
   
           if not hosts:
               msg = _("Is the appropriate service running?")
               raise exception.NoValidHost(reason=msg)
   
           remote_ip = context.remote_address
   
           if remote_ip.startswith('10.1'):
               hostname_prefix = 'doc'
           elif remote_ip.startswith('10.2'):
               hostname_prefix = 'ops'
           else:
               hostname_prefix = 'dev'
   
           hosts = self._filter_hosts(hosts, hostname_prefix)
           host = hosts[int(random.random() * len(hosts))]
   
           LOG.debug(_("Request from %(remote_ip)s scheduled to %(host)s")
                     % locals())
   
           return host
   
       def schedule_run_instance(self, context, request_spec,
                                 admin_password, injected_files,
                                 requested_networks, is_first_time,
                                 filter_properties):
           """Attempts to run the instance"""
           instance_uuids = request_spec.get('instance_uuids')
           for num, instance_uuid in enumerate(instance_uuids):
               request_spec['instance_properties']['launch_index'] = num
               try:
                   host = self._schedule(context, 'compute', request_spec,
                                         filter_properties)
                   updated_instance = driver.instance_update_db(context,
                                                                instance_uuid)
                   self.compute_rpcapi.run_instance(context,
                                                    instance=updated_instance, host=host,
                                                    requested_networks=requested_networks,
                                                    injected_files=injected_files,
                                                    admin_password=admin_password,
                                                    is_first_time=is_first_time,
                                                    request_spec=request_spec,
                                                    filter_properties=filter_properties)
               except Exception as ex:
                   # NOTE(vish): we don't reraise the exception here to make sure
                   # that all instances in the request get set to
                   # error properly
                   driver.handle_schedule_error(context, ex, instance_uuid,
                                            request_spec)
   
       def schedule_prep_resize(self, context, image, request_spec,
                                filter_properties, instance, instance_type,
                                reservations):
           """Select a target for resize."""
           host = self._schedule(context, 'compute', request_spec,
                                 filter_properties)
           self.compute_rpcapi.prep_resize(context, image, instance,
                                           instance_type, host, reservations)
   

   There is a lot of useful information in context, request_spec, and filter_properties that you can use to decide where to schedule the instance. To find out more about what properties are available you can insert the following log statements into the schedule_run_instance method of the scheduler above.

   LOG.debug(_("context = %(context)s") % {'context': context.__dict__})LOG.debug(_("request_spec = %(request_spec)s") % locals())LOG.debug(_("filter_properties = %(filter_properties)s") % locals())

3. To plug this scheduler into Nova you’ll need to edit one configuration file.

   LOG$ vim /etc/nova/nova.conf

4. Find the compute_scheduler_driver config and change it like so.

   LOGcompute_scheduler_driver=nova.scheduler.ip_scheduler.IPScheduler

5. Restart the Nova scheduler service to make Nova use your scheduler. Start by switching to the n-sch screen.

   1. Press Ctrl-A followed by pressing 8

   2. Press Ctrl-C to kill the service

   3. Press Up Arrow to bring up the last command

   4. Press Enter to run it

6. Test your scheduler with the Nova CLI. Start by switching to the shell screen and finish by switching back to the n-sch screen to check the log output.

   1. Press Ctrl-A followed by pressing 0

   2. cd ~/devstack

   3. source openrc

   4. IMAGE_ID=`nova image-list | egrep cirros | egrep -v "kernel|ramdisk" | awk '{print $2}'`

   5. nova boot --flavor 1 --image $IMAGE_ID scheduler-test

   6. Press Ctrl-A followed by pressing 8

7. Among the log statements you’ll see the line.

   LOG2013-02-27 17:39:31 DEBUG nova.scheduler.ip_scheduler [req-... demo demo] Request from 50.56.172.78 scheduled to
   devstack-nova from (pid=4118) _schedule /opt/stack/nova/nova/scheduler/ip_scheduler.py:73