diff --git a/doc/markdown/quick_start_guide.md b/doc/markdown/quick_start_guide.md index 13c5d31..765ec22 100644 --- a/doc/markdown/quick_start_guide.md +++ b/doc/markdown/quick_start_guide.md @@ -9,183 +9,116 @@ ## Overview -SwiftOnFile allows any POSIX complaint filesystem to be used as the -backend to the object store OpenStack Swift. +SwiftOnFile allows any POSIX complaint filesystem to be used as the backend to the object store OpenStack Swift. -The following guide will get you quickly started with a SwiftOnFile -environment on a Fedora or RHEL/CentOS system. This guide is a -great way to begin using SwiftOnFile, and can be easily deployed on -a single virtual machine. The final result will be a single SwiftOnFile -node. +The following guide assumes you have a running [OpenStack Swift SAIO setup][], and you want to extend this setup to try SwiftOnFile as Storage Policy on a XFS/gluster volume. This will get you quickly started with a SwiftOnFile environment on a Fedora or RHEL/CentOS system. -> NOTE: In SwiftOnFile a swift account is a mounted FS under path mentioned -in configuration parameter.It is assumed you have two xattrr supporting FS mounted -under certain paths.We suggest you to start with two xfs formatted FS then you can -move on to other FS that supports xattr.For setting up gluster volume in particular -you can look here [GlusterFS Quick Start Guide][] +This guide will not go on detail on how to prepare a Swift SAIO setup or how to create a gluster volume (or other FS).This guide assumes you know about these technologies, if you require any help in setting those please refer to the link provided. ## System Setup ### Prerequisites on CentOS/RHEL -On CentOS/RHEL you may need to EPEL repo.Please refer to -[EPEL][] for more information on how to setup the EPEL repo. -SwiftOnfile requires corresponding OpenStack Swift release packages.There are two -possible ways to get OpenStack Swift packages. +1. OpenStack SAIO deployment on Fedora20 onwards +2. One xfs/glusterfs volume - named vol -1. Get & build the OpenStack swift source from github.(This should work for all linux flavors) +>Note: Swift SAIO deployment should contain Storage Policy code changes. Initialy Storage Policy feature was developed seprately in openstack swift feature/ec branch, and it is now merged in master branch. The latest OpenStack Swift2.0 release also contain storage policy code. - a.) Git clone the required branch (assume icehouse) - ~~~ - git clone -b icehouse-stable https://github.com/openstack/swift.git - ~~~ - b.)Install the prerequisite - ~~~ - python-pip install -r requirements.txt - python-pip install -r test-requirements.txt - ~~~ - c.)Install the packages - ~~~ - python setup.py install - ~~~ - d.) Please refer to the OpenStack swift SAIO guide, - if you face any difficulty in doing above. +Each xfs/glusterfs volume will be defined as a separate storage policy. -2. Use the Stable RDO release (Fedora/RHEL/CentOS) +### Install SwiftOnfile +1. Before you begin swiftonfile setup please ensure you have OpenStack Swift SAIO setup up & running. Please refer to the SAIO guide for this. +2. cd ~; git clone https://github.com/swiftonfile/swiftonfile.git +3. cd ~/swiftonfile;python setup.py develop;cd ~ - a.) Please setup corresponding Red Hat RDO release repo (assume icehouse) - ~~~ - yum install -y http://repos.fedorapeople.org/repos/openstack/openstack-icehouse/rdo-release-icehouse-3.noarch.rpm - ~~~ - b.) Install required rpms: - ~~~ - yum install -y openstack-swift-proxy openstack-swift-account openstack-swift-container\ - openstack-swift-object memcached python-swiftclient python-keystoneclient - ~~~ - -### Install SwiftOnFile -1. Install from source - - a.) Git clone the required branch (assume icehouse) - - git clone -b icehouse https://github.com/swiftonfile/swiftonfile.git - - b.)Install the prerequisite - - python-pip install -r requirements.txt - python-pip install -r test-requirements.txt - - c.)Install the packages - - python setup.py install - -2. Using RPMs - - a.) Download the rpms from [Jenkins CI][] - - b.)Install the RPM by executing the following: - yum install -y - -### Enabling Swift Service available accross reboots -~~~ -chkconfig openstack-swift-proxy on -chkconfig openstack-swift-account on -chkconfig openstack-swift-container on -chkconfig openstack-swift-object on -~~~ - -#### Fedora 19 Adjustment -Currently SwiftOnFile requires its processes to be run as `root`. You need to -edit the `openstack-swift-*.service` files in -`/etc/systemd/system/multi-user.target.wants` and change the `User` entry value -to `root`. - -Then run the following command to reload the configuration: +### Configure SwiftOnFile as Storage Policy +1. A SAIO setup mimic a four node swift setup and should have four object server running.Add another object server for SwiftOnFile by setting the following configurations in the file /etc/swift/object-server/5.conf: ~~~ -systemctl --system daemon-reload +[DEFAULT] +devices = /mnt/xfsvols/ +mount_check = false +bind_port = 6050 +max_clients = 1024 +workers = 1 +disable_fallocate = true + +[pipeline:main] +pipeline = object-server + +[app:object-server] +use = egg:gluster_swift#object +user = root +log_facility = LOG_LOCAL2 +log_level = DEBUG +log_requests = on +disk_chunk_size = 65536 ~~~ -### Configuration -As with OpenStack Swift, SwiftOnFile uses `/etc/swift` as the -directory containing the configuration files. You will need to base -the configuration files on the template files provided. On new RPM based -installations, the simplest way is to copy the `*.conf-gluster` -files to `*.conf` files as follows: +>Note: The parameter 'devices' tells about the path where your xfs/glusterfs volume is mounted. The sub directory under which your volume is mounted will be called volume name. For ex: You have a xfs formated partition /dev/sdb1, and you mounted it under /mnt/xfsvols/vol, then your volume name would be 'vol'& and the parameter 'devices' would contain value '/mnt/xfsvols'. + +2. Edit /etc/swift.conf to add swiftonfile as a storage policy: ~~~ -cd /etc/swift -for tmpl in *.conf-gluster ; do cp ${tmpl} ${tmpl%.*}.conf; done +[storage-policy:0] +name = swift + +[storage-policy:1] +name = swiftonfile-test +default = yes ~~~ -Else you can base your config files on [test code ][]. - -#### Generate Ring Files -You now need to generate the ring files, which inform SwiftOnFile -which FS volumes are accessible over the object storage interface. -This is a borrowed legacy from gluster-swift and it will soon change. -This script uses OpenStack Swift ring builder with the fundamental -assumption that the replication/sync/HA/etc are provided by underlying FS -(gluster in this case).The format is +3. Edit the remakerings script to prepare rings for this new storage policy: ~~~ -gluster-swift-gen-builders [mount-point-name] [mount-point-name...] +swift-ring-builder object-1.builder create 1 1 1 +swift-ring-builder object-1.builder add r1z1-127.0.0.1:6050/vol 1 +swift-ring-builder object-1.builder rebalance ~~~ -Where *mount-point-name* is the name of the a directory in the path mentioned in -/etc/swift{account,object,container}.conf under the section [DEFAULT] -for parameter 'devices'.For ex: If 'device' parameter has the value '/mnt/FS-objects' -and you mounted two gluster/xfs volumes on /mnt/FS-objects/gfs-vol1 & -/mnt/FS-objects/gfs-vol2 then the command would look like this: -~~~ -gluster-swift-gen-builders gfs-vol1 gfs-vol2 -~~~ - -### Start swift services using the following commands: +4. Restart swift services to reflect new changes: ~~~ -service openstack-swift-object start -service openstack-swift-container start -service openstack-swift-account start -service openstack-swift-proxy start +swift-init all restart ~~~ -Or using -~~~ -swift-init main start -~~~ + +5. Running functional tests: TBD + ## Using SwiftOnFile +It is assumed that you are still using 'tempauth' as authnetication method, which is default in SAIO deployment. + +### Get the token +~~~ +curl -v -H 'X-Auth-User: test:tester' -H "X-Auth-key: testing" -k http://localhost:8080/auth/v1.0 +~~~ +Use 'X-Auth-Token' & 'X-Storage-Url' returned in above request for all sucequent request. ### Create a container Create a container using the following command: ~~~ -curl -v -X PUT http://localhost:8080/v1/AUTH_gfs-vol1/mycontainer +curl -v -X PUT -H 'X-Auth-Token: AUTH_XXXX' http://localhost:8080/v1/AUTH_test/mycontainer ~~~ -It should return `HTTP/1.1 201 Created` on a successful creation. You can -also confirm that the container has been created by inspecting the FS: - -~~~ -ls /mnt/FS-object/gfs-vol1 -~~~ +It should return `HTTP/1.1 201 Created` on a successful creation. #### Create an object -You can now place an object in the container you have just created: +You can now place an object in the container you have just dreated: ~~~ echo "Hello World" > mytestfile -curl -v -X PUT -T mytestfile http://localhost:8080/v1/AUTH_gfs-vol1/mycontainer/mytestfile +curl -v -X PUT -T mytestfile 'X-Auth-Token: AUTH_XXXX' http://localhost:8080/v1/AUTH_test/mycontainer/mytestfile ~~~ To confirm that the object has been written correctly, you can compare the test file with the object you created: ~~~ -cat /mnt/FS-object/gfs-vol1/mycontainer/mytestfile +cat /mnt/xfsvols/vol/test/mycontainer/mytestfile ~~~ #### Request the object @@ -193,7 +126,7 @@ Now you can retreive the object and inspect its contents using the following commands: ~~~ -curl -v -X GET -o newfile http://localhost:8080/v1/AUTH_gfs-vol1/mycontainer/mytestfile +curl -v -X GET -o newfile http://localhost:8080/v1/AUTH_test/mycontainer/mytestfile cat newfile ~~~ @@ -214,4 +147,5 @@ For more information, please visit the following links: [Authentication Services Start Guide]: auth_guide.md [EPEL]: https://fedoraproject.org/wiki/EPEL [Jenkins CI]: http://build.gluster.org/job/swiftonfile-builds/lastSuccessfulBuild/artifact/build/ -[test code] : https://github.com/swiftonfile/swiftonfile/tree/master/test/functional_auth/tempauth/conf/ +[test code]: https://github.com/swiftonfile/swiftonfile/tree/master/test/functional_auth/tempauth/conf/ +[OpenStack Swift SAIO setup]: http://docs.openstack.org/developer/swift/development_saio.html