openstack/swift
Code Issues Proposed changes
c007d0296e
swift/doc/source/development_saio.rst

18 KiB
Raw Blame History

SAIO - Swift All In One

Instructions for setting up a development VM

This documents setting up a virtual machine for doing Swift development. The virtual machine will emulate running a four node Swift cluster.

Additional information about setting up a Swift development snapshot on other distributions is available on the wiki at http://wiki.openstack.org/SAIOInstructions.

Installing dependencies and the core code

  • As root on guest (you'll have to log in as you, then sudo su -):
    1. apt-get install python-software-properties
    2. add-apt-repository ppa:swift-core/ppa
    3. apt-get update
    4. apt-get install curl gcc bzr memcached python-configobj python-coverage python-dev python-nose python-setuptools python-simplejson python-xattr sqlite3 xfsprogs python-webob python-eventlet python-greenlet python-pastedeploy
    5. Install anything else you want, like screen, ssh, vim, etc.
    6. Next, choose either see partition-section or loopback-section.

Using a partition for storage

If you are going to use a separate partition for Swift data, be sure to add another device when

creating the VM, and follow these instructions.

  1. fdisk /dev/sdb (set up a single partition)

  2. mkfs.xfs -i size=1024 /dev/sdb1

  3. Edit /etc/fstab and add

    /dev/sdb1 /mnt/sdb1 xfs noatime,nodiratime,nobarrier,logbufs=8 0 0

  4. mkdir /mnt/sdb1

  5. mount /mnt/sdb1

  6. mkdir /mnt/sdb1/1 /mnt/sdb1/2 /mnt/sdb1/3 /mnt/sdb1/4 /mnt/sdb1/test

  7. chown <your-user-name>:<your-group-name> /mnt/sdb1/*

  8. mkdir /srv

  9. for x in {1..4}; do ln -s /mnt/sdb1/$x /srv/$x; done

  10. mkdir -p /etc/swift/object-server /etc/swift/container-server /etc/swift/account-server /srv/1/node/sdb1 /srv/2/node/sdb2 /srv/3/node/sdb3 /srv/4/node/sdb4 /var/run/swift

  11. chown -R <your-user-name>:<your-group-name> /etc/swift /srv/[1-4]/ /var/run/swift -- Make sure to include the trailing slash after /srv/[1-4]/

  12. Add to /etc/rc.local (before the exit 0):

    mkdir /var/run/swift
chown <your-user-name>:<your-group-name> /var/run/swift

  13. Next, skip to rsync-section.

Using a loopback device for storage

If you want to use a loopback device instead of another partition, follow these instructions.

  1. dd if=/dev/zero of=/srv/swift-disk bs=1024 count=0 seek=1000000

    (modify seek to make a larger or smaller partition)

  2. mkfs.xfs -i size=1024 /srv/swift-disk

  3. Edit /etc/fstab and add

    /srv/swift-disk /mnt/sdb1 xfs loop,noatime,nodiratime,nobarrier,logbufs=8 0 0

  4. mkdir /mnt/sdb1

  5. mount /mnt/sdb1

  6. mkdir /mnt/sdb1/1 /mnt/sdb1/2 /mnt/sdb1/3 /mnt/sdb1/4 /mnt/sdb1/test

  7. chown <your-user-name>:<your-group-name> /mnt/sdb1/*

  8. mkdir /srv

  9. for x in {1..4}; do ln -s /mnt/sdb1/$x /srv/$x; done

  10. mkdir -p /etc/swift/object-server /etc/swift/container-server /etc/swift/account-server /srv/1/node/sdb1 /srv/2/node/sdb2 /srv/3/node/sdb3 /srv/4/node/sdb4 /var/run/swift

  11. chown -R <your-user-name>:<your-group-name> /etc/swift /srv/[1-4]/ /var/run/swift -- Make sure to include the trailing slash after /srv/[1-4]/

  12. Add to /etc/rc.local (before the exit 0):

    mkdir /var/run/swift
chown <your-user-name>:<your-group-name> /var/run/swift

Setting up rsync

  1. Create /etc/rsyncd.conf:

    uid = <Your user name>
gid = <Your group name>
log file = /var/log/rsyncd.log
pid file = /var/run/rsyncd.pid
address = 127.0.0.1

[account6012]
max connections = 25
path = /srv/1/node/
read only = false
lock file = /var/lock/account6012.lock

[account6022]
max connections = 25
path = /srv/2/node/
read only = false
lock file = /var/lock/account6022.lock

[account6032]
max connections = 25
path = /srv/3/node/
read only = false
lock file = /var/lock/account6032.lock

[account6042]
max connections = 25
path = /srv/4/node/
read only = false
lock file = /var/lock/account6042.lock


[container6011]
max connections = 25
path = /srv/1/node/
read only = false
lock file = /var/lock/container6011.lock

[container6021]
max connections = 25
path = /srv/2/node/
read only = false
lock file = /var/lock/container6021.lock

[container6031]
max connections = 25
path = /srv/3/node/
read only = false
lock file = /var/lock/container6031.lock

[container6041]
max connections = 25
path = /srv/4/node/
read only = false
lock file = /var/lock/container6041.lock


[object6010]
max connections = 25
path = /srv/1/node/
read only = false
lock file = /var/lock/object6010.lock

[object6020]
max connections = 25
path = /srv/2/node/
read only = false
lock file = /var/lock/object6020.lock

[object6030]
max connections = 25
path = /srv/3/node/
read only = false
lock file = /var/lock/object6030.lock

[object6040]
max connections = 25
path = /srv/4/node/
read only = false
lock file = /var/lock/object6040.lock

  2. Edit the following line in /etc/default/rsync:

    RSYNC_ENABLE=true

  3. service rsync restart

Getting the code and setting up test environment

Sample configuration files are provided with all defaults in line-by-line comments.

Do these commands as you on guest:

  1. mkdir ~/bin

  2. Create `~/.bazaar/bazaar.conf`:

    [DEFAULT]
        email = Your Name <your-email-address>

  3. If you are using launchpad to get the code or make changes, run bzr launchpad-login <launchpad_id>

  4. Create the swift repo with bzr init-repo swift

  5. Check out your bzr branch of swift, for example: cd ~/swift; bzr branch lp:swift trunk

  6. cd ~/swift/trunk; sudo python setup.py develop

  7. Edit ~/.bashrc and add to the end:

    export PATH_TO_TEST_XFS=/mnt/sdb1/test
export SWIFT_TEST_CONFIG_FILE=/etc/swift/func_test.conf
export PATH=${PATH}:~/bin

  8. . ~/.bashrc

Configuring each node

Sample configuration files are provided with all defaults in line-by-line comments.

  1. Create `/etc/swift/auth-server.conf`:

    [DEFAULT]
user = <your-user-name>

[pipeline:main]
pipeline = auth-server

[app:auth-server]
use = egg:swift#auth
default_cluster_url = http://127.0.0.1:8080/v1
# Highly recommended to change this.
super_admin_key = devauth

  2. Create `/etc/swift/proxy-server.conf`:

    [DEFAULT]
bind_port = 8080
user = <your-user-name>

[pipeline:main]
pipeline = healthcheck cache auth proxy-server

[app:proxy-server]
use = egg:swift#proxy

[filter:auth]
use = egg:swift#auth

[filter:healthcheck]
use = egg:swift#healthcheck

[filter:cache]
use = egg:swift#memcache

  3. Create `/etc/swift/swift.conf`:

    [swift-hash]
# random unique string that can never change (DO NOT LOSE)
swift_hash_path_suffix = changeme

  4. Create `/etc/swift/account-server/1.conf`:

    [DEFAULT]
devices = /srv/1/node
mount_check = false
bind_port = 6012
user = <your-user-name>

[pipeline:main]
pipeline = account-server

[app:account-server]
use = egg:swift#account

[account-replicator]
vm_test_mode = yes

[account-auditor]

[account-reaper]

  5. Create `/etc/swift/account-server/2.conf`:

    [DEFAULT]
devices = /srv/2/node
mount_check = false
bind_port = 6022
user = <your-user-name>

[pipeline:main]
pipeline = account-server

[app:account-server]
use = egg:swift#account

[account-replicator]
vm_test_mode = yes

[account-auditor]

[account-reaper]

  6. Create `/etc/swift/account-server/3.conf`:

    [DEFAULT]
devices = /srv/3/node
mount_check = false
bind_port = 6032
user = <your-user-name>

[pipeline:main]
pipeline = account-server

[app:account-server]
use = egg:swift#account

[account-replicator]
vm_test_mode = yes

[account-auditor]

[account-reaper]

  7. Create `/etc/swift/account-server/4.conf`:

    [DEFAULT]
devices = /srv/4/node
mount_check = false
bind_port = 6042
user = <your-user-name>

[pipeline:main]
pipeline = account-server

[app:account-server]
use = egg:swift#account

[account-replicator]
vm_test_mode = yes

[account-auditor]

[account-reaper]

  8. Create `/etc/swift/container-server/1.conf`:

    [DEFAULT]
devices = /srv/1/node
mount_check = false
bind_port = 6011
user = <your-user-name>

[pipeline:main]
pipeline = container-server

[app:container-server]
use = egg:swift#container

[container-replicator]
vm_test_mode = yes

[container-updater]

[container-auditor]

  9. Create `/etc/swift/container-server/2.conf`:

    [DEFAULT]
devices = /srv/2/node
mount_check = false
bind_port = 6021
user = <your-user-name>

[pipeline:main]
pipeline = container-server

[app:container-server]
use = egg:swift#container

[container-replicator]
vm_test_mode = yes

[container-updater]

[container-auditor]

  10. Create `/etc/swift/container-server/3.conf`:

    [DEFAULT]
devices = /srv/3/node
mount_check = false
bind_port = 6031
user = <your-user-name>

[pipeline:main]
pipeline = container-server

[app:container-server]
use = egg:swift#container

[container-replicator]
vm_test_mode = yes

[container-updater]

[container-auditor]

  11. Create `/etc/swift/container-server/4.conf`:

    [DEFAULT]
devices = /srv/4/node
mount_check = false
bind_port = 6041
user = <your-user-name>

[pipeline:main]
pipeline = container-server

[app:container-server]
use = egg:swift#container

[container-replicator]
vm_test_mode = yes

[container-updater]

[container-auditor]

  12. Create `/etc/swift/object-server/1.conf`:

    [DEFAULT]
devices = /srv/1/node
mount_check = false
bind_port = 6010
user = <your-user-name>

[pipeline:main]
pipeline = object-server

[app:object-server]
use = egg:swift#object

[object-replicator]
vm_test_mode = yes

[object-updater]

[object-auditor]

  13. Create `/etc/swift/object-server/2.conf`:

    [DEFAULT]
devices = /srv/2/node
mount_check = false
bind_port = 6020
user = <your-user-name>

[pipeline:main]
pipeline = object-server

[app:object-server]
use = egg:swift#object

[object-replicator]
vm_test_mode = yes

[object-updater]

[object-auditor]

  14. Create `/etc/swift/object-server/3.conf`:

    [DEFAULT]
devices = /srv/3/node
mount_check = false
bind_port = 6030
user = <your-user-name>

[pipeline:main]
pipeline = object-server

[app:object-server]
use = egg:swift#object

[object-replicator]
vm_test_mode = yes

[object-updater]

[object-auditor]

  15. Create `/etc/swift/object-server/4.conf`:

    [DEFAULT]
devices = /srv/4/node
mount_check = false
bind_port = 6040
user = <your-user-name>

[pipeline:main]
pipeline = object-server

[app:object-server]
use = egg:swift#object

[object-replicator]
vm_test_mode = yes

[object-updater]

[object-auditor]

Setting up scripts for running Swift

  1. Create ~/bin/resetswift. If you are using a loopback device substitute /dev/sdb1 with `/srv/swift-disk`:

    #!/bin/bash

swift-init all stop
sleep 5
sudo umount /mnt/sdb1
sudo mkfs.xfs -f -i size=1024 /dev/sdb1
sudo mount /mnt/sdb1
sudo mkdir /mnt/sdb1/1 /mnt/sdb1/2 /mnt/sdb1/3 /mnt/sdb1/4 /mnt/sdb1/test
sudo chown <your-user-name>:<your-group-name> /mnt/sdb1/*
mkdir -p /srv/1/node/sdb1 /srv/2/node/sdb2 /srv/3/node/sdb3 /srv/4/node/sdb4
sudo rm -f /var/log/debug /var/log/messages /var/log/rsyncd.log /var/log/syslog
sudo service rsyslog restart
sudo service memcached restart

  2. Create `~/bin/remakerings`:

    #!/bin/bash

cd /etc/swift

rm -f *.builder *.ring.gz backups/*.builder backups/*.ring.gz

swift-ring-builder object.builder create 18 3 1
swift-ring-builder object.builder add z1-127.0.0.1:6010/sdb1 1
swift-ring-builder object.builder add z2-127.0.0.1:6020/sdb2 1
swift-ring-builder object.builder add z3-127.0.0.1:6030/sdb3 1
swift-ring-builder object.builder add z4-127.0.0.1:6040/sdb4 1
swift-ring-builder object.builder rebalance
swift-ring-builder container.builder create 18 3 1
swift-ring-builder container.builder add z1-127.0.0.1:6011/sdb1 1
swift-ring-builder container.builder add z2-127.0.0.1:6021/sdb2 1
swift-ring-builder container.builder add z3-127.0.0.1:6031/sdb3 1
swift-ring-builder container.builder add z4-127.0.0.1:6041/sdb4 1
swift-ring-builder container.builder rebalance
swift-ring-builder account.builder create 18 3 1
swift-ring-builder account.builder add z1-127.0.0.1:6012/sdb1 1
swift-ring-builder account.builder add z2-127.0.0.1:6022/sdb2 1
swift-ring-builder account.builder add z3-127.0.0.1:6032/sdb3 1
swift-ring-builder account.builder add z4-127.0.0.1:6042/sdb4 1
swift-ring-builder account.builder rebalance

  3. Create `~/bin/startmain`:

    #!/bin/bash

swift-init auth-server start
swift-init proxy-server start
swift-init account-server start
swift-init container-server start
swift-init object-server start

  4. Create `~/bin/startrest`:

    #!/bin/bash

# Replace devauth with whatever your super_admin key is (recorded in
# /etc/swift/auth-server.conf).
swift-auth-recreate-accounts -K devauth
swift-init object-updater start
swift-init container-updater start
swift-init object-replicator start
swift-init container-replicator start
swift-init account-replicator start
swift-init object-auditor start
swift-init container-auditor start
swift-init account-auditor start
swift-init account-reaper start

  5. chmod +x ~/bin/*

  6. remakerings

  7. cd ~/swift/trunk; ./.unittests

  8. startmain (The Unable to increase file descriptor limit. Running as non-root? warnings are expected and ok.)

  9. swift-auth-add-user -K devauth -a test tester testing # Replace devauth with whatever your super_admin key is (recorded in /etc/swift/auth-server.conf).

  10. Get an X-Storage-Url and `X-Auth-Token`: curl -v -H 'X-Storage-User: test:tester' -H 'X-Storage-Pass: testing' http://127.0.0.1:11000/v1.0

  11. Check that you can GET account: curl -v -H 'X-Auth-Token: <token-from-x-auth-token-above>' <url-from-x-storage-url-above>

  12. Check that st works: st -A http://127.0.0.1:11000/v1.0 -U test:tester -K testing stat

  13. swift-auth-add-user -K devauth -a test2 tester2 testing2 # Replace devauth with whatever your super_admin key is (recorded in /etc/swift/auth-server.conf).

  14. swift-auth-add-user -K devauth test tester3 testing3 # Replace devauth with whatever your super_admin key is (recorded in /etc/swift/auth-server.conf).

  15. cp ~/swift/trunk/test/functional/sample.conf /etc/swift/func_test.conf

  16. cd ~/swift/trunk; ./.functests (Note: functional tests will first delete everything in the configured accounts.)

  17. cd ~/swift/trunk; ./.probetests (Note: probe tests will reset your environment as they call resetswift for each test.)

If you plan to work on documentation (and who doesn't?!):

On Ubuntu:
  1. sudo apt-get install python-sphinx installs Sphinx.
  2. python setup.py build_sphinx builds the documentation.
On MacOS:
  1. sudo easy_install -U sphinx installs Sphinx.
  2. python setup.py build_sphinx builds the documentation.

Debugging Issues

If all doesn't go as planned, and tests fail, or you can't auth, or something doesn't work, here are some good starting places to look for issues:

  1. Everything is logged in /var/log/syslog, so that is a good first place to look for errors (most likely python tracebacks).
  2. Make sure all of the server processes are running. For the base functionality, the Proxy, Account, Container, Object and Auth servers should be running
  3. If one of the servers are not running, and no errors are logged to syslog, it may be useful to try to start the server manually, for example: swift-object-server /etc/swift/object-server/1.conf will start the object server. If there are problems not showing up in syslog, then you will likely see the traceback on startup.