diff --git a/doc/manpages/account-server.conf.5 b/doc/manpages/account-server.conf.5 new file mode 100644 index 0000000000..d77510343c --- /dev/null +++ b/doc/manpages/account-server.conf.5 @@ -0,0 +1,228 @@ +.\" +.\" Author: Joao Marcelo Martins or +.\" Copyright (c) 2010-2011 OpenStack, LLC. +.\" +.\" 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. +.\" +.TH account-server.conf 5 "8/26/2011" "Linux" "OpenStack Swift" + +.SH NAME +.LP +.B account-server.conf +\- configuration file for the openstack-swift account server + + + +.SH SYNOPSIS +.LP +.B account-server.conf + + + +.SH DESCRIPTION +.PP +This is the configuration file used by the account server and other account +background services, such as; replicator, auditor and reaper. + +The configuration file follows the python-pastedeploy syntax. The file is divided +into sections, which are enclosed by square brackets. Each section will contain a +certain number of key/value parameters which are described later. + +Any line that begins with a '#' symbol is ignored. + +You can find more information about python-pastedeploy configuration format at +\fIhttp://pythonpaste.org/deploy/#config-format\fR + + + +.SH GLOBAL SECTION +.PD 1 +.RS 0 +This is indicated by section named [DEFAULT]. Below are the parameters that +are acceptable within this section. + +.IP "\fBbind_ip\fR" +IP address the account server should bind to. The default is 0.0.0.0 which will make +it bind to all available addresses. +.IP "\fBbind_port\fR" +TCP port the account server should bind to. The default is 6002. +.IP \fBbacklog\fR +TCP backlog. Maximum number of allowed pending connections. The default value is 4096. +.IP \fBworkers\fR +Number of account server workers to fork. The default is 1. +.IP \fBuser\fR +The system user that the account server will run as. The default is swift. +.IP \fBswift_dir\fR +Swift configuration directory. The default is /etc/swift. +.IP \fBdevices\fR +Parent directory or where devices are mounted. Default is /srv/node. +.IP \fBmount_check\fR +Whether or not check if the devices are mounted to prevent accidentally writing to +the root device. The default is set to true. +.IP \fBlog_name\fR +Label used when logging. The default is swift. +.IP \fBlog_facility\fR +Syslog log facility. The default is LOG_LOCAL0. +.IP \fBlog_level\fR +Logging level. The default is INFO. +.RE +.PD + + + +.SH PIPELINE SECTION +.PD 1 +.RS 0 +This is indicated by section name [pipeline:main]. Below are the parameters that +are acceptable within this section. + +.IP "\fBpipeline\fR" +It is used when you need apply a number of filters. It is a list of filters +ended by an application. The default should be "healthcheck +account-server" +.RE +.PD + + + +.SH APP SECTION +.PD 1 +.RS 0 +This is indicated by section name [app:account-server]. Below are the parameters +that are acceptable within this section. +.IP "\fBuse\fR" +Entry point for paste.deploy for the account server. This is the reference to the installed python egg. +The default is \fBegg:swift#account\fR. +.IP "\fBset log_name\fR +Label used when logging. The default is account-server. +.IP "\fBset log_facility\fR +Syslog log facility. The default is LOG_LOCAL0. +.IP "\fB set log_level\fR +Logging level. The default is INFO. +.IP "\fB set log_requests\fR +Enables request logging. The default is True. +.RE +.PD + + + +.SH FILTER SECTION +.PD 1 +.RS 0 +Any section that has its name prefixed by "filter:" indicates a filter section. +Filters are used to specify configuration parameters for specific swift middlewares. +Below are the filters available and respective acceptable parameters. +.IP "\fB[filter:healthcheck]\fR" +.RE +.RS 3 +.IP "\fBuse\fR" +Entry point for paste.deploy for the healthcheck middleware. This is the reference to the installed python egg. +The default is \fBegg:swift#healthcheck\fR. +.RE +.PD + + + +.SH ADDITIONAL SECTIONS +.PD 1 +.RS 0 +The following sections are used by other swift-account services, such as replicator, +auditor and reaper. +.IP "\fB[account-replicator]\fR" +.RE +.RS 3 +.IP \fBlog_name\fR +Label used when logging. The default is account-replicator. +.IP \fBlog_facility\fR +Syslog log facility. The default is LOG_LOCAL0. +.IP \fBlog_level\fR +Logging level. The default is INFO. +.IP \fBvm_test_mode\fR +Indicates that you are using a VM environment. The default is no. +.IP \fBper_diff\fR +The default is 1000. +.IP \fBconcurrency\fR +Number of replication workers to spawn. The default is 8. +.IP \fBrun_pause\fR +Time in seconds to wait between replication passes. The default is 10. +.IP \fBerror_suppression_interval\fR +How long without an error before a node's error count is reset. This will also be how long before a node is re-enabled after suppression is triggered. +The default is 60 seconds. +.IP \fBerror_suppression_limit\fR +How many errors can accumulate before a node is temporarily ignored. The default +is 10 seconds. +.IP \fBnode_timeout\fR +Request timeout to external services. The default is 10 seconds. +.IP \fBconn_timeout\fR +Connection timeout to external services. The default is 0.5 seconds. +.IP \fBreclaim_age\fR +Time elapsed in seconds before an account can be reclaimed. The default is +604800 seconds. +.RE + + + +.RS 0 +.IP "\fB[account-auditor]\fR" +.RE +.RS 3 +.IP \fBlog_name\fR +Label used when logging. The default is account-auditor. +.IP \fBlog_facility\fR +Syslog log facility. The default is LOG_LOCAL0. +.IP \fBlog_level\fR +Logging level. The default is INFO. +.IP \fBinterval\fR +Will audit, at most, 1 account per device per interval. The default is 1800 seconds. +.RE + + + +.RS 0 +.IP "\fB[account-reaper]\fR" +.RE +.RS 3 +.IP \fBlog_name\fR +Label used when logging. The default is account-reaper. +.IP \fBlog_facility\fR +Syslog log facility. The default is LOG_LOCAL0. +.IP \fBlog_level\fR +Logging level. The default is INFO. +.IP \fBconcurrency\fR +Number of reaper workers to spawn. The default is 25. +.IP \fBinterval\fR +Minimum time for a pass to take. The default is 3600 seconds. +.IP \fBnode_timeout\fR +Request timeout to external services. The default is 10 seconds. +.IP \fBconn_timeout\fR +Connection timeout to external services. The default is 0.5 seconds. +.RE +.PD + + + + +.SH DOCUMENTATION +.LP +More in depth documentation about the swift-account-server and +also Openstack-Swift as a whole can be found at +.BI http://swift.openstack.org/admin_guide.html +and +.BI http://swift.openstack.org + + +.SH "SEE ALSO" +.BR swift-account-server(1), + + diff --git a/doc/manpages/container-server.conf.5 b/doc/manpages/container-server.conf.5 new file mode 100644 index 0000000000..5f15ffe076 --- /dev/null +++ b/doc/manpages/container-server.conf.5 @@ -0,0 +1,249 @@ +.\" +.\" Author: Joao Marcelo Martins or +.\" Copyright (c) 2010-2011 OpenStack, LLC. +.\" +.\" 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. +.\" +.TH container-server.conf 5 "8/26/2011" "Linux" "OpenStack Swift" + +.SH NAME +.LP +.B container-server.conf +\- configuration file for the openstack-swift container server + + + +.SH SYNOPSIS +.LP +.B container-server.conf + + + +.SH DESCRIPTION +.PP +This is the configuration file used by the container server and other container +background services, such as; replicator, updater, auditor and sync. + +The configuration file follows the python-pastedeploy syntax. The file is divided +into sections, which are enclosed by square brackets. Each section will contain a +certain number of key/value parameters which are described later. + +Any line that begins with a '#' symbol is ignored. + +You can find more information about python-pastedeploy configuration format at +\fIhttp://pythonpaste.org/deploy/#config-format\fR + + + +.SH GLOBAL SECTION +.PD 1 +.RS 0 +This is indicated by section named [DEFAULT]. Below are the parameters that +are acceptable within this section. + +.IP "\fBbind_ip\fR" +IP address the container server should bind to. The default is 0.0.0.0 which will make +it bind to all available addresses. +.IP "\fBbind_port\fR" +TCP port the container server should bind to. The default is 6001. +.IP \fBbacklog\fR +TCP backlog. Maximum number of allowed pending connections. The default value is 4096. +.IP \fBworkers\fR +Number of container server workers to fork. The default is 1. +.IP \fBuser\fR +The system user that the container server will run as. The default is swift. +.IP \fBswift_dir\fR +Swift configuration directory. The default is /etc/swift. +.IP \fBdevices\fR +Parent directory or where devices are mounted. Default is /srv/node. +.IP \fBmount_check\fR +Whether or not check if the devices are mounted to prevent accidentally writing to +the root device. The default is set to true. +.IP \fBlog_name\fR +Label used when logging. The default is swift. +.IP \fBlog_facility\fR +Syslog log facility. The default is LOG_LOCAL0. +.IP \fBlog_level\fR +Logging level. The default is INFO. +.RE +.PD + + + +.SH PIPELINE SECTION +.PD 1 +.RS 0 +This is indicated by section name [pipeline:main]. Below are the parameters that +are acceptable within this section. + +.IP "\fBpipeline\fR" +It is used when you need to apply a number of filters. It is a list of filters +ended by an application. The default should be \fB"healthcheck +container-server"\fR +.RE +.PD + + + +.SH APP SECTION +.PD 1 +.RS 0 +This is indicated by section name [app:container-server]. Below are the parameters +that are acceptable within this section. +.IP "\fBuse\fR" +Entry point for paste.deploy for the container server. This is the reference to the installed python egg. +The default is \fBegg:swift#container\fR. +.IP "\fBset log_name\fR +Label used when logging. The default is container-server. +.IP "\fBset log_facility\fR +Syslog log facility. The default is LOG_LOCAL0. +.IP "\fB set log_level\fR +Logging level. The default is INFO. +.IP "\fB set log_requests\fR +Enables request logging. The default is True. +.IP \fBnode_timeout\fR +Request timeout to external services. The default is 3 seconds. +.IP \fBconn_timeout\fR +Connection timeout to external services. The default is 0.5 seconds. +.RE +.PD + + + +.SH FILTER SECTION +.PD 1 +.RS 0 +Any section that has its name prefixed by "filter:" indicates a filter section. +Filters are used to specify configuration parameters for specific swift middlewares. +Below are the filters available and respective acceptable parameters. +.IP "\fB[filter:healthcheck]\fR" +.RE +.RS 3 +.IP "\fBuse\fR" +Entry point for paste.deploy for the healthcheck middleware. This is the reference to the installed python egg. +The default is \fBegg:swift#healthcheck\fR. +.RE +.PD + + + +.SH ADDITIONAL SECTIONS +.PD 1 +.RS 0 +The following sections are used by other swift-container services, such as replicator, +updater, auditor and sync. +.IP "\fB[container-replicator]\fR" +.RE +.RS 3 +.IP \fBlog_name\fR +Label used when logging. The default is container-replicator. +.IP \fBlog_facility\fR +Syslog log facility. The default is LOG_LOCAL0. +.IP \fBlog_level\fR +Logging level. The default is INFO. +.IP \fBvm_test_mode\fR +Indicates that you are using a VM environment. The default is no. +.IP \fBper_diff\fR +The default is 1000. +.IP \fBconcurrency\fR +Number of replication workers to spawn. The default is 8. +.IP \fBrun_pause\fR +Time in seconds to wait between replication passes. The default is 30. +.IP \fBnode_timeout\fR +Request timeout to external services. The default is 10 seconds. +.IP \fBconn_timeout\fR +Connection timeout to external services. The default is 0.5 seconds. +.IP \fBreclaim_age\fR +Time elapsed in seconds before an container can be reclaimed. The default is +604800 seconds. +.RE + + +.RS 0 +.IP "\fB[container-updater]\fR" +.RE +.RS 3 +.IP \fBlog_name\fR +Label used when logging. The default is container-updater. +.IP \fBlog_facility\fR +Syslog log facility. The default is LOG_LOCAL0. +.IP \fBlog_level\fR +Logging level. The default is INFO. +.IP \fBinterval\fR +Minimum time for a pass to take. The default is 300 seconds. +.IP \fBconcurrency\fR +Number of reaper workers to spawn. The default is 4. +.IP \fBnode_timeout\fR +Request timeout to external services. The default is 3 seconds. +.IP \fBconn_timeout\fR +Connection timeout to external services. The default is 0.5 seconds. +.IP \fBslowdown = 0.01\fR +Slowdown will sleep that amount between containers. The default is 0.01 seconds. +.IP \fBaccount_suppression_time\fR +Seconds to suppress updating an account that has generated an error. The default is 60 seconds. +.RE +.PD + + +.RS 0 +.IP "\fB[container-auditor]\fR" +.RE +.RS 3 +.IP \fBlog_name\fR +Label used when logging. The default is container-auditor. +.IP \fBlog_facility\fR +Syslog log facility. The default is LOG_LOCAL0. +.IP \fBlog_level\fR +Logging level. The default is INFO. +.IP \fBinterval\fR +Will audit, at most, 1 container per device per interval. The default is 1800 seconds. +.RE + + + +.RS 0 +.IP "\fB[container-sync]\fR" +.RE +.RS 3 +.IP \fBlog_name\fR +Label used when logging. The default is container-sync. +.IP \fBlog_facility\fR +Syslog log facility. The default is LOG_LOCAL0. +.IP \fBlog_level\fR +Logging level. The default is INFO. +.IP \fBsync_proxy\fR +If you need to use an HTTP Proxy, set it here; defaults to no proxy. +.IP \fBinterval\fR +Will audit, at most, each container once per interval. The default is 300 seconds. +.IP \fBcontainer_time\fR +Maximum amount of time to spend syncing each container per pass. The default is 60 seconds. +.RE +.PD + + + + +.SH DOCUMENTATION +.LP +More in depth documentation about the swift-container-server and +also Openstack-Swift as a whole can be found at +.BI http://swift.openstack.org/admin_guide.html +and +.BI http://swift.openstack.org + + +.SH "SEE ALSO" +.BR swift-container-server(1), + + diff --git a/doc/manpages/dispersion.conf.5 b/doc/manpages/dispersion.conf.5 new file mode 100644 index 0000000000..d9175ee28e --- /dev/null +++ b/doc/manpages/dispersion.conf.5 @@ -0,0 +1,83 @@ +.\" +.\" Author: Joao Marcelo Martins or +.\" Copyright (c) 2010-2011 OpenStack, LLC. +.\" +.\" 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. +.\" +.TH dispersion.conf 5 "8/26/2011" "Linux" "OpenStack Swift" + +.SH NAME +.LP +.B dispersion.conf +\- configuration file for the openstack-swift dispersion tools + +.SH SYNOPSIS +.LP +.B dispersion.conf + +.SH DESCRIPTION +.PP +This is the configuration file used by the dispersion populate and report tools. +The file format consists of the '[dispersion]' module as the header and available parameters. +Any line that begins with a '#' symbol is ignored. + + +.SH PARAMETERS +.PD 1 +.RS 0 +.IP "\fBauth_url\fR" +Authentication system URL +.IP "\fBauth_user\fR" +Authentication system account/user name +.IP "\fBauth_key\fR" +Authentication system account/user password +.IP "\fBswift_dir\fR" +Location of openstack-swift configuration and ring files +.IP "\fBdispersion_coverage\fR" +Percentage of partition coverage to use. The default is 1 +.IP "\fBretries\fR" +Maximum number of attempts +.IP "\fBconcurrency\fR" +Maximum number of concurrencies to +.RE +.PD + +.SH SAMPLE +.PD 0 +.RS 0 +.IP "[dispersion]" +.IP "auth_url = https://127.0.0.1:443/auth/v1.0" +.IP "auth_user = dpstats:dpstats" +.IP "auth_key = dpstats" +.IP "swift_dir = /etc/swift" +.IP "# dispersion_coverage = 1" +.IP "# retries = 5" +.IP "# concurrency = 25" +.RE +.PD + + +.SH DOCUMENTATION +.LP +More in depth documentation about the swift-dispersion utilities and +also Openstack-Swift as a whole can be found at +.BI http://swift.openstack.org/admin_guide.html#cluster-health +and +.BI http://swift.openstack.org + + +.SH "SEE ALSO" +.BR swift-dispersion-report(1), +.BR swift-dispersion-populate(1) + diff --git a/doc/manpages/object-server.conf.5 b/doc/manpages/object-server.conf.5 new file mode 100644 index 0000000000..5031d58ac4 --- /dev/null +++ b/doc/manpages/object-server.conf.5 @@ -0,0 +1,261 @@ +.\" +.\" Author: Joao Marcelo Martins or +.\" Copyright (c) 2010-2011 OpenStack, LLC. +.\" +.\" 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. +.\" +.TH object-server.conf 5 "8/26/2011" "Linux" "OpenStack Swift" + +.SH NAME +.LP +.B object-server.conf +\- configuration file for the openstack-swift object server + + + +.SH SYNOPSIS +.LP +.B object-server.conf + + + +.SH DESCRIPTION +.PP +This is the configuration file used by the object server and other object +background services, such as; replicator, updater and auditor. + +The configuration file follows the python-pastedeploy syntax. The file is divided +into sections, which are enclosed by square brackets. Each section will contain a +certain number of key/value parameters which are described later. + +Any line that begins with a '#' symbol is ignored. + +You can find more information about python-pastedeploy configuration format at +\fIhttp://pythonpaste.org/deploy/#config-format\fR + + + +.SH GLOBAL SECTION +.PD 1 +.RS 0 +This is indicated by section named [DEFAULT]. Below are the parameters that +are acceptable within this section. + +.IP "\fBbind_ip\fR" +IP address the object server should bind to. The default is 0.0.0.0 which will make +it bind to all available addresses. +.IP "\fBbind_port\fR" +TCP port the object server should bind to. The default is 6000. +.IP \fBbacklog\fR +TCP backlog. Maximum number of allowed pending connections. The default value is 4096. +.IP \fBworkers\fR +Number of object server workers to fork. The default is 1. +.IP \fBuser\fR +The system user that the object server will run as. The default is swift. +.IP \fBswift_dir\fR +Swift configuration directory. The default is /etc/swift. +.IP \fBdevices\fR +Parent directory or where devices are mounted. Default is /srv/node. +.IP \fBmount_check\fR +Whether or not check if the devices are mounted to prevent accidentally writing to +the root device. The default is set to true. +.IP \fBlog_name\fR +Label used when logging. The default is swift. +.IP \fBlog_facility\fR +Syslog log facility. The default is LOG_LOCAL0. +.IP \fBlog_level\fR +Logging level. The default is INFO. +.RE +.PD + + + +.SH PIPELINE SECTION +.PD 1 +.RS 0 +This is indicated by section name [pipeline:main]. Below are the parameters that +are acceptable within this section. + +.IP "\fBpipeline\fR" +It is used when you need to apply a number of filters. It is a list of filters +ended by an application. The default should be \fB"healthcheck recon +object-server"\fR +.RE +.PD + + + +.SH APP SECTION +.PD 1 +.RS 0 +This is indicated by section name [app:object-server]. Below are the parameters +that are acceptable within this section. +.IP "\fBuse\fR" +Entry point for paste.deploy for the object server. This is the reference to the installed python egg. +The default is \fBegg:swift#object\fR. +.IP "\fBset log_name\fR +Label used when logging. The default is object-server. +.IP "\fBset log_facility\fR +Syslog log facility. The default is LOG_LOCAL0. +.IP "\fB set log_level\fR +Logging level. The default is INFO. +.IP "\fB set log_requests\fR +Enables request logging. The default is True. +.IP \fBnode_timeout\fR +Request timeout to external services. The default is 3 seconds. +.IP \fBconn_timeout\fR +Connection timeout to external services. The default is 0.5 seconds. +.RE +.PD + + + +.SH FILTER SECTION +.PD 1 +.RS 0 +Any section that has its name prefixed by "filter:" indicates a filter section. +Filters are used to specify configuration parameters for specific swift middlewares. +Below are the filters available and respective acceptable parameters. +.IP "\fB[filter:healthcheck]\fR" +.RE +.RS 3 +.IP "\fBuse\fR" +Entry point for paste.deploy for the healthcheck middleware. This is the reference to the installed python egg. +The default is \fBegg:swift#healthcheck\fR. +.RE + +.RS 0 +.IP "\fB[filter:recon]\fR" +.RE +.RS 3 +.IP "\fBuse\fR" +Entry point for paste.deploy for the healthcheck middleware. This is the reference to the installed python egg. +The default is \fBegg:swift#recon\fR. +.IP "\fBrecon_cache_path\fR" +The recon_cache_path simply sets the directory where stats for a few items will be stored. +Depending on the method of deployment you may need to create this directory manually +and ensure that swift has read/write.The default is /var/cache/swift. +.RE +.PD + + + +.SH ADDITIONAL SECTIONS +.PD 1 +.RS 0 +The following sections are used by other swift-object services, such as replicator, +updater, auditor. +.IP "\fB[object-replicator]\fR" +.RE +.RS 3 +.IP \fBlog_name\fR +Label used when logging. The default is object-replicator. +.IP \fBlog_facility\fR +Syslog log facility. The default is LOG_LOCAL0. +.IP \fBlog_level\fR +Logging level. The default is INFO. +.IP \fBvm_test_mode\fR +Indicates that you are using a VM environment. The default is no. +.IP \fBdaemonize\fR +Whether or not to run replication as a daemon. The default is yes. +.IP \fBrun_pause\fR +Time in seconds to wait between replication passes. The default is 30. +.IP \fBconcurrency\fR +Number of replication workers to spawn. The default is 1. +.IP \fBstats_interval\fR +Interval in seconds between logging replication statistics. The default is 300. +.IP \fBrsync_timeout\fR +Max duration of a partition rsync. The default is 900 seconds. +.IP \fBrsync_io_timeout\fR +Passed to rsync for I/O OP timeout. The default is 30 seconds. +.IP \fBhttp_timeout\fR +Max duration of an HTTP request. The default is 60 seconds. +.IP \fBlockup_timeout\fR +Attempts to kill all workers if nothing replicates for lockup_timeout seconds. The +default is 1800 seconds. +.IP \fBreclaim_age\fR +Time elapsed in seconds before an object can be reclaimed. The default is +604800 seconds. +.IP \fBrecon_enable\fR +Enable logging of replication stats for recon. The default is on. +.IP "\fBrecon_cache_path\fR" +The recon_cache_path simply sets the directory where stats for a few items will be stored. +Depending on the method of deployment you may need to create this directory manually +and ensure that swift has read/write.The default is /var/cache/swift. +.RE + + +.RS 0 +.IP "\fB[object-updater]\fR" +.RE +.RS 3 +.IP \fBlog_name\fR +Label used when logging. The default is object-updater. +.IP \fBlog_facility\fR +Syslog log facility. The default is LOG_LOCAL0. +.IP \fBlog_level\fR +Logging level. The default is INFO. +.IP \fBinterval\fR +Minimum time for a pass to take. The default is 300 seconds. +.IP \fBconcurrency\fR +Number of reaper workers to spawn. The default is 1. +.IP \fBnode_timeout\fR +Request timeout to external services. The default is 10 seconds. +.IP \fBconn_timeout\fR +Connection timeout to external services. The default is 0.5 seconds. +.IP \fBslowdown = 0.01\fR +Slowdown will sleep that amount between objects. The default is 0.01 seconds. +.RE +.PD + + +.RS 0 +.IP "\fB[object-auditor]\fR" +.RE +.RS 3 +.IP \fBlog_name\fR +Label used when logging. The default is object-auditor. +.IP \fBlog_facility\fR +Syslog log facility. The default is LOG_LOCAL0. +.IP \fBlog_level\fR +Logging level. The default is INFO. + +.IP \fBfiles_per_second\fR +Maximum files audited per second. Should be tuned according to individual +system specs. 0 is unlimited. The default is 20. +.IP \fBbytes_per_second\fR +Maximum bytes audited per second. Should be tuned according to individual +system specs. 0 is unlimited. The default is 10000000. +.IP \fBlog_time\fR +The default is 3600 seconds. +.IP \fBzero_byte_files_per_second\fR +The default is 50. +.RE + + + + +.SH DOCUMENTATION +.LP +More in depth documentation about the swift-object-server and +also Openstack-Swift as a whole can be found at +.BI http://swift.openstack.org/admin_guide.html +and +.BI http://swift.openstack.org + + +.SH "SEE ALSO" +.BR swift-object-server(1), + + diff --git a/doc/manpages/proxy-server.conf.5 b/doc/manpages/proxy-server.conf.5 new file mode 100644 index 0000000000..4979e4da22 --- /dev/null +++ b/doc/manpages/proxy-server.conf.5 @@ -0,0 +1,448 @@ +.\" +.\" Author: Joao Marcelo Martins or +.\" Copyright (c) 2010-2011 OpenStack, LLC. +.\" +.\" 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. +.\" +.TH proxy-server.conf 5 "8/26/2011" "Linux" "OpenStack Swift" + +.SH NAME +.LP +.B proxy-server.conf +\- configuration file for the openstack-swift proxy server + + + +.SH SYNOPSIS +.LP +.B proxy-server.conf + + + +.SH DESCRIPTION +.PP +This is the configuration file used by the proxy server and other proxy middlewares. + +The configuration file follows the python-pastedeploy syntax. The file is divided +into sections, which are enclosed by square brackets. Each section will contain a +certain number of key/value parameters which are described later. + +Any line that begins with a '#' symbol is ignored. + +You can find more information about python-pastedeploy configuration format at +\fIhttp://pythonpaste.org/deploy/#config-format\fR + + + +.SH GLOBAL SECTION +.PD 1 +.RS 0 +This is indicated by section named [DEFAULT]. Below are the parameters that +are acceptable within this section. + +.IP "\fBbind_ip\fR" +IP address the proxy server should bind to. The default is 0.0.0.0 which will make +it bind to all available addresses. +.IP "\fBbind_port\fR" +TCP port the proxy server should bind to. The default is 80. +.IP \fBbacklog\fR +TCP backlog. Maximum number of allowed pending connections. The default value is 4096. +.IP \fBworkers\fR +Number of container server workers to fork. The default is 1. +.IP \fBuser\fR +The system user that the container server will run as. The default is swift. +.IP \fBswift_dir\fR +Swift configuration directory. The default is /etc/swift. +.IP \fBcert_file\fR +Location of the SSL certificate file. The default path is /etc/swift/proxy.crt. This is +disabled by default. +.IP \fBkey_file\fR +Location of the SSL certificate key file. The default path is /etc/swift/proxy.key. This is +disabled by default. +.IP \fBlog_name\fR +Label used when logging. The default is swift. +.IP \fBlog_facility\fR +Syslog log facility. The default is LOG_LOCAL0. +.IP \fBlog_level\fR +Logging level. The default is INFO. +.RE +.PD + + + +.SH PIPELINE SECTION +.PD 1 +.RS 0 +This is indicated by section name [pipeline:main]. Below are the parameters that +are acceptable within this section. + +.IP "\fBpipeline\fR" +It is used when you need apply a number of filters. It is a list of filters +ended by an application. The default should be \fB"catch_errors healthcheck +cache ratelimit tempauth proxy-server"\fR +.RE +.PD + + + +.SH FILTER SECTION +.PD 1 +.RS 0 +Any section that has its name prefixed by "filter:" indicates a filter section. +Filters are used to specify configuration parameters for specific swift middlewares. +Below are the filters available and respective acceptable parameters. +.IP "\fB[filter:healthcheck]\fR" +.RE +.RS 3 +.IP "\fBuse\fR" +Entry point for paste.deploy for the healthcheck middleware. This is the reference to the installed python egg. +The default is \fBegg:swift#healthcheck\fR. +.RE + + +.RS 0 +.IP "\fB[filter:tempauth]\fR" +.RE +.RS 3 +.IP \fBuse\fR +Entry point for paste.deploy for the tempauth middleware. This is the reference to the installed python egg. +The default is \fBegg:swift#tempauth\fR. +.IP "\fBset log_name\fR" +Label used when logging. The default is tempauth. +.IP "\fBset log_facility\fR" +Syslog log facility. The default is LOG_LOCAL0. +.IP "\fBset log_level\fR " +Logging level. The default is INFO. +.IP "\fBset log_headers\fR " +Enables the ability to log request headers. The default is False. +.IP \fBreseller_prefix\fR +The reseller prefix will verify a token begins with this prefix before even +attempting to validate it. Also, with authorization, only Swift storage accounts +with this prefix will be authorized by this middleware. Useful if multiple auth +systems are in use for one Swift cluster. The default is AUTH. +.IP \fBauth_prefix\fR +The auth prefix will cause requests beginning with this prefix to be routed +to the auth subsystem, for granting tokens, etc. The default is /auth/. +.IP \fBtoken_life\fR +This is the time in seconds before the token expires. The default is 86400. +.IP \fBallowed_sync_hosts\fR +This is a comma separated list of hosts allowed to send X-Container-Sync-Key requests. +.IP \fBuser__\fR +Lastly, you need to list all the accounts/users you want here. The format is: +user__ = [group] [group] [...] [storage_url] + +There are special groups of: \fI.reseller_admin\fR who can do anything to any account for this auth +and also \fI.admin\fR who can do anything within the account. + +If neither of these groups are specified, the user can only access containers that +have been explicitly allowed for them by a \fI.admin\fR or \fI.reseller_admin\fR. + The trailing optional storage_url allows you to specify an alternate url to hand +back to the user upon authentication. If not specified, this defaults to +\fIhttp[s]://:/v1/_\fR where http or https depends +on whether cert_file is specified in the [DEFAULT] section, and are based +on the [DEFAULT] section's bind_ip and bind_port (falling back to 127.0.0.1 and 8080), + is from this section, and is from the user__ name. + +Here are example entries, required for running the tests: +.RE + +.PD 0 +.RS 10 .IP "user_admin_admin = admin .admin .reseller_admin" +.IP "user_test_tester = testing .admin" +.IP "user_test2_tester2 = testing2 .admin" +.IP "user_test_tester3 = testing3" +.RE +.PD + +.RS 0 +.IP "\fB[filter:healthcheck]\fR" +.RE +.RS 3 +.IP \fBuse\fR +Entry point for paste.deploy for the healthcheck middleware. This is the reference to the installed python egg. +The default is \fBegg:swift#healthcheck\fR. +.IP "\fBset log_name\fR" +Label used when logging. The default is healthcheck. +.IP "\fBset log_facility\fR" +Syslog log facility. The default is LOG_LOCAL0. +.IP "\fBset log_level\fR " +Logging level. The default is INFO. +.IP "\fBset log_headers\fR " +Enables the ability to log request headers. The default is False. +.RE + + + +.RS 0 +.IP "\fB[filter:cache]\fR" +.RE + +Caching middleware that manages caching in swift. + +.RS 3 +.IP \fBuse\fR +Entry point for paste.deploy for the memcache middleware. This is the reference to the installed python egg. +The default is \fBegg:swift#memcache\fR. +.IP "\fBset log_name\fR" +Label used when logging. The default is memcache. +.IP "\fBset log_facility\fR" +Syslog log facility. The default is LOG_LOCAL0. +.IP "\fBset log_level\fR " +Logging level. The default is INFO. +.IP "\fBset log_headers\fR " +Enables the ability to log request headers. The default is False. +.IP \fBmemcache_servers\fR +The memcache servers that are available. This can be a list separated by commas. The default +is 127.0.0.1:11211. +.RE + + + +.RS 0 +.IP "\fB[filter:ratelimit]\fR" +.RE + +Rate limits requests on both an Account and Container level. Limits are configurable. + +.RS 3 +.IP \fBuse\fR +Entry point for paste.deploy for the ratelimit middleware. This is the reference to the installed python egg. +The default is \fBegg:swift#ratelimit\fR. +.IP "\fBset log_name\fR" +Label used when logging. The default is ratelimit. +.IP "\fBset log_facility\fR" +Syslog log facility. The default is LOG_LOCAL0. +.IP "\fBset log_level\fR " +Logging level. The default is INFO. +.IP "\fBset log_headers\fR " +Enables the ability to log request headers. The default is False. +.IP \fBclock_accuracy\fR +This should represent how accurate the proxy servers' system clocks are with each other. +1000 means that all the proxies' clock are accurate to each other within 1 millisecond. +No ratelimit should be higher than the clock accuracy. The default is 1000. +.IP \fBmax_sleep_time_seconds\fR +App will immediately return a 498 response if the necessary sleep time ever exceeds +the given max_sleep_time_seconds. The default is 60 seconds. +.IP \fBlog_sleep_time_seconds\fR +To allow visibility into rate limiting set this value > 0 and all sleeps greater than +the number will be logged. If set to 0 means disabled. The default is 0. +.IP \fBrate_buffer_seconds\fR +Number of seconds the rate counter can drop and be allowed to catch up +(at a faster than listed rate). A larger number will result in larger spikes in +rate but better average accuracy. The default is 5. +.IP \fBaccount_ratelimit\fR +If set, will limit PUT and DELETE requests to /account_name/container_name. Number is +in requests per second. If set to 0 means disabled. The default is 0. +.IP \fBaccount_whitelist\fR +Comma separated lists of account names that will not be rate limited. The default is ''. +.IP \fBaccount_blacklist\fR +Comma separated lists of account names that will not be allowed. Returns a 497 response. +The default is ''. +.IP \fBcontainer_ratelimit_size\fR +When set with container_limit_x = r: for containers of size x, limit requests per second +to r. Will limit PUT, DELETE, and POST requests to /a/c/o. The default is ''. +.RE + + + +.RS 0 +.IP "\fB[filter:domain_remap]\fR" +.RE + +Middleware that translates container and account parts of a domain to path parameters that the proxy server understands. + +\fIcontainer.account.storageurl/object\fR gets translated to +\fIcontainer.account.storageurl/path_root/account/container/object\fR + + \fIaccount.storageurl/path_root/container/object\fR gets translated to +\fIaccount.storageurl/path_root/account/container/object\fR + +.RS 3 +.IP \fBuse\fR +Entry point for paste.deploy for the domain_remap middleware. This is the reference to the installed python egg. +The default is \fBegg:swift#domain_remap\fR. +.IP "\fBset log_name\fR" +Label used when logging. The default is domain_remap. +.IP "\fBset log_facility\fR" +Syslog log facility. The default is LOG_LOCAL0. +.IP "\fBset log_level\fR " +Logging level. The default is INFO. +.IP "\fBset log_headers\fR" +Enables the ability to log request headers. The default is False. +.IP \fBstorage_domain\fR +The domain to be used by the middleware. +.IP \fBpath_root\fR +The path root value for the storage URL. The default is v1. +.IP \fBreseller_prefixes\fR +Browsers can convert a host header to lowercase, so check that reseller +prefix on the account is the correct case. This is done by comparing the +items in the reseller_prefixes config option to the found prefix. If they +match except for case, the item from reseller_prefixes will be used +instead of the found reseller prefix. The reseller_prefixes list is exclusive. +If defined, any request with an account prefix not in that list will be ignored +by this middleware. Defaults to 'AUTH'. +.RE + + + +.RS 0 +.IP "\fB[filter:catch_errors]\fR" +.RE +.RS 3 +.IP \fBuse\fR +Entry point for paste.deploy for the catch_errors middleware. This is the reference to the installed python egg. +The default is \fBegg:swift#catch_errors\fR. +.IP "\fBset log_name\fR" +Label used when logging. The default is catch_errors. +.IP "\fBset log_facility\fR" +Syslog log facility. The default is LOG_LOCAL0. +.IP "\fBset log_level\fR " +Logging level. The default is INFO. +.IP "\fBset log_headers\fR" +Enables the ability to log request headers. The default is False. +.RE + + + +.RS 0 +.IP "\fB[filter:cname_lookup]\fR" +.RE + +Note: this middleware requires python-dnspython + +.RS 3 +.IP \fBuse\fR +Entry point for paste.deploy for the cname_lookup middleware. This is the reference to the installed python egg. +The default is \fBegg:swift#cname_lookup\fR. +.IP "\fBset log_name\fR" +Label used when logging. The default is cname_lookup. +.IP "\fBset log_facility\fR" +Syslog log facility. The default is LOG_LOCAL0. +.IP "\fBset log_level\fR " +Logging level. The default is INFO. +.IP "\fBset log_headers\fR" +Enables the ability to log request headers. The default is False. +.IP \fBstorage_domain\fR +The domain to be used by the middleware. +.IP \fBlookup_depth\fR +How deep in the CNAME chain to look for something that matches the storage domain. +The default is 1. +.RE + + + +.RS 0 +.IP "\fB[filter:staticweb]\fR" +.RE + +Note: Put staticweb just after your auth filter(s) in the pipeline + +.RS 3 +.IP \fBuse\fR +Entry point for paste.deploy for the staticweb middleware. This is the reference to the installed python egg. +The default is \fBegg:swift#staticweb\fR. +.IP \fBcache_timeout\fR +Seconds to cache container x-container-meta-web-* header values. The default is 300 seconds. +.IP "\fBset log_name\fR" +Label used when logging. The default is staticweb. +.IP "\fBset log_facility\fR" +Syslog log facility. The default is LOG_LOCAL0. +.IP "\fBset log_level\fR " +Logging level. The default is INFO. +.IP "\fBset log_headers\fR" +Enables the ability to log request headers. The default is False. +.IP "\fBset access_log_name\fR" +Label used when logging. The default is staticweb. +.IP "\fBset access_log_facility\fR" +Syslog log facility. The default is LOG_LOCAL0. +.IP "\fBset access_log_level\fR " +Logging level. The default is INFO. +.RE + +.PD + + + + +.SH APP SECTION +.PD 1 +.RS 0 +This is indicated by section name [app:proxy-server]. Below are the parameters +that are acceptable within this section. +.IP \fBuse\fR +Entry point for paste.deploy for the proxy server. This is the reference to the installed python egg. +The default is \fBegg:swift#proxy\fR. +.IP "\fBset log_name\fR +Label used when logging. The default is proxy-server. +.IP "\fBset log_facility\fR +Syslog log facility. The default is LOG_LOCAL0. +.IP "\fB set log_level\fR +Logging level. The default is INFO. +.IP "\fBset access_log_name\fR" +Label used when logging. The default is proxy-server. +.IP "\fBset access_log_facility\fR" +Syslog log facility. The default is LOG_LOCAL0. +.IP "\fBset access_log_level\fR " +Logging level. The default is INFO. +.IP "\fB set log_requests\fR +Enables request logging. The default is False. +.IP \fBrecheck_account_existence\fR +Cache timeout in seconds to send memcached for account existence. The default is 60 seconds. +.IP \fBrecheck_container_existence\fR +Cache timeout in seconds to send memcached for container existence. The default is 60 seconds. +.IP \fBobject_chunk_size\fR +Chunk size to read from object servers. The default is 8192. +.IP \fBclient_chunk_size\fR +Chunk size to read from clients. The default is 8192. +.IP \fBnode_timeout\fR +Request timeout to external services. The default is 10 seconds. +.IP \fBclient_timeoutt\fR +Timeout to read one chunk from a client. The default is 60 seconds. +.IP \fBconn_timeout\fR +Connection timeout to external services. The default is 0.5 seconds. +.IP \fBerror_suppression_interval\fR +Time in seconds that must elapse since the last error for a node to +be considered no longer error limited. The default is 60 seconds. +.IP \fBerror_suppression_limit\fR +Error count to consider a node error limited. The default is 10. +.IP \fBallow_account_management\fR +Whether account PUTs and DELETEs are even callable. If set to 'true' any authorized +user may create and delete accounts; if 'false' no one, even authorized, can. The default +is false. +.IP \fBobject_post_as_copy\fR +Set object_post_as_copy = false to turn on fast posts where only the metadata changes +are stored as new and the original data file is kept in place. This makes for quicker +posts; but since the container metadata isn't updated in this mode, features like +container sync won't be able to sync posts. The default is True. +.IP \fBaccount_autocreate\fR +If set to 'true' authorized accounts that do not yet exist within the Swift cluster +will be automatically created. The default is set to false. +.RE +.PD + + + +.SH DOCUMENTATION +.LP +More in depth documentation about the swift-proxy-server and +also Openstack-Swift as a whole can be found at +.BI http://swift.openstack.org/admin_guide.html +and +.BI http://swift.openstack.org + + +.SH "SEE ALSO" +.BR swift-proxy-server(1), + + diff --git a/doc/manpages/swift-account-auditor.1 b/doc/manpages/swift-account-auditor.1 new file mode 100644 index 0000000000..5754ad7571 --- /dev/null +++ b/doc/manpages/swift-account-auditor.1 @@ -0,0 +1,71 @@ +.\" +.\" Author: Joao Marcelo Martins or +.\" Copyright (c) 2010-2011 OpenStack, LLC. +.\" +.\" 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. +.\" +.TH swift-account-auditor 1 "8/26/2011" "Linux" "OpenStack Swift" + +.SH NAME +.LP +.B swift-account-auditor +\- Openstack-swift account auditor + +.SH SYNOPSIS +.LP +.B swift-account-auditor +[CONFIG] [-h|--help] [-v|--verbose] [-o|--once] + +.SH DESCRIPTION +.PP + +The account auditor crawls the local account system checking the integrity of accounts +objects. If corruption is found (in the case of bit rot, for example), the file is +quarantined, and replication will replace the bad file from another replica. + +The options are as follows: + +.RS 4 +.PD 0 +.IP "-v" +.IP "--verbose" +.RS 4 +.IP "log to console" +.RE +.IP "-o" +.IP "--once" +.RS 4 +.IP "only run one pass of daemon" +.RE +.PD +.RE + +.SH DOCUMENTATION +.LP +More in depth documentation in regards to +.BI swift-account-auditor +and also about Openstack-Swift as a whole can be found at +.BI http://swift.openstack.org/index.html + +.SH FILES +.IP "\fI/usr/share/doc/swift-account/account-server.conf-sample\fR" 0 +Sample configuration file for swift-account services + +.IP "\fI/etc/init.d/swift-account-auditor\fR" 0 +Account auditor init.d script + + + +.SH "SEE ALSO" +.BR account-server.conf(5) diff --git a/doc/manpages/swift-account-reaper.1 b/doc/manpages/swift-account-reaper.1 new file mode 100644 index 0000000000..e63dfaa811 --- /dev/null +++ b/doc/manpages/swift-account-reaper.1 @@ -0,0 +1,77 @@ +.\" +.\" Author: Joao Marcelo Martins or +.\" Copyright (c) 2010-2011 OpenStack, LLC. +.\" +.\" 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. +.\" +.TH swift-account-reaper 1 "8/26/2011" "Linux" "OpenStack Swift" + +.SH NAME +.LP +.B swift-account-reaper +\- Openstack-swift account reaper + +.SH SYNOPSIS +.LP +.B swift-account-reaper +[CONFIG] [-h|--help] [-v|--verbose] [-o|--once] + +.SH DESCRIPTION +.PP +Removes data from status=DELETED accounts. These are accounts that have +been asked to be removed by the reseller via services remove_storage_account +XMLRPC call. +.PP +The account is not deleted immediately by the services call, but instead +the account is simply marked for deletion by setting the status column in +the account_stat table of the account database. This account reaper scans +for such accounts and removes the data in the background. The background +deletion process will occur on the primary account server for the account. + +The options are as follows: + +.RS 4 +.PD 0 +.IP "-v" +.IP "--verbose" +.RS 4 +.IP "log to console" +.RE +.IP "-o" +.IP "--once" +.RS 4 +.IP "only run one pass of daemon" +.RE +.PD +.RE + + +.SH DOCUMENTATION +.LP +More in depth documentation in regards to +.BI swift-object-auditor +and also about Openstack-Swift as a whole can be found at +.BI http://swift.openstack.org/index.html + +.SH FILES +.IP "\fI/usr/share/doc/swift-account/account-server.conf-sample\fR" 0 +Sample configuration file for swift-account services + +.IP "\fI/etc/init.d/swift-account-reaper\fR" 0 +Account reaper init.d script + + + +.SH "SEE ALSO" +.BR account-server.conf(5) diff --git a/doc/manpages/swift-account-replicator.1 b/doc/manpages/swift-account-replicator.1 new file mode 100644 index 0000000000..47fe99f36b --- /dev/null +++ b/doc/manpages/swift-account-replicator.1 @@ -0,0 +1,79 @@ +.\" +.\" Author: Joao Marcelo Martins or +.\" Copyright (c) 2010-2011 OpenStack, LLC. +.\" +.\" 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. +.\" +.TH swift-account-replicator 1 "8/26/2011" "Linux" "OpenStack Swift" + +.SH NAME +.LP +.B swift-account-replicator +\- Openstack-swift account replicator + +.SH SYNOPSIS +.LP +.B swift-account-replicator +[CONFIG] [-h|--help] [-v|--verbose] [-o|--once] + +.SH DESCRIPTION +.PP +Replication is designed to keep the system in a consistent state in the face of +temporary error conditions like network outages or drive failures. The replication +processes compare local data with each remote copy to ensure they all contain the +latest version. Account replication uses a combination of hashes and shared high +water marks to quickly compare subsections of each partition. +.PP +Replication updates are push based. Account replication push missing records over +HTTP or rsync whole database files. The replicator also ensures that data is removed +from the system. When an account item is deleted a tombstone is set as the latest +version of the item. The replicator will see the tombstone and ensure that the item +is removed from the entire system. + +The options are as follows: + +.RS 4 +.PD 0 +.IP "-v" +.IP "--verbose" +.RS 4 +.IP "log to console" +.RE +.IP "-o" +.IP "--once" +.RS 4 +.IP "only run one pass of daemon" +.RE +.PD +.RE + + +.SH DOCUMENTATION +.LP +More in depth documentation in regards to +.BI swift-account-replicator +and also about Openstack-Swift as a whole can be found at +.BI http://swift.openstack.org/index.html + +.SH FILES +.IP "\fI/usr/share/doc/swift-account/account-server.conf-sample\fR" 0 +Sample configuration file for swift-account services + +.IP "\fI/etc/init.d/swift-account-replicator\fR" 0 +Account replicator init.d script + + + +.SH "SEE ALSO" +.BR account-server.conf(5) diff --git a/doc/manpages/swift-account-server.1 b/doc/manpages/swift-account-server.1 new file mode 100644 index 0000000000..98b8d51767 --- /dev/null +++ b/doc/manpages/swift-account-server.1 @@ -0,0 +1,54 @@ +.\" +.\" Author: Joao Marcelo Martins or +.\" Copyright (c) 2010-2011 OpenStack, LLC. +.\" +.\" 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. +.\" +.TH swift-account-server 1 "8/26/2011" "Linux" "OpenStack Swift" + +.SH NAME +.LP +.B swift-account-server +\- Openstack-swift account server + +.SH SYNOPSIS +.LP +.B swift-account-server +[CONFIG] [-h|--help] [-v|--verbose] + +.SH DESCRIPTION +.PP +The Account Server's primary job is to handle listings of containers. The listings +are stored as sqlite database files, and replicated across the cluster similar to how +objects are. + +.SH DOCUMENTATION +.LP +More in depth documentation in regards to +.BI swift-account-server +and also about Openstack-Swift as a whole can be found at +.BI http://swift.openstack.org/index.html +and +.BI http://docs.openstack.org + +.SH FILES +.IP "\fI/usr/share/doc/swift-account/account-server.conf-sample\fR" 0 +Sample configuration file for swift-account server +.IP "\fI/etc/init.d/swift-account\fR" 0 +Account server init.d script + + + +.SH "SEE ALSO" +.BR account-server.conf(5) diff --git a/doc/manpages/swift-container-auditor.1 b/doc/manpages/swift-container-auditor.1 new file mode 100644 index 0000000000..abeb9f6930 --- /dev/null +++ b/doc/manpages/swift-container-auditor.1 @@ -0,0 +1,72 @@ +.\" +.\" Author: Joao Marcelo Martins or +.\" Copyright (c) 2010-2011 OpenStack, LLC. +.\" +.\" 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. +.\" +.TH swift-container-auditor 1 "8/26/2011" "Linux" "OpenStack Swift" + +.SH NAME +.LP +.B swift-container-auditor +\- Openstack-swift container auditor + +.SH SYNOPSIS +.LP +.B swift-container-auditor +[CONFIG] [-h|--help] [-v|--verbose] [-o|--once] + +.SH DESCRIPTION +.PP + +The container auditor crawls the local container system checking the integrity of container +objects. If corruption is found (in the case of bit rot, for example), the file is +quarantined, and replication will replace the bad file from another replica. + +The options are as follows: + +.RS 4 +.PD 0 +.IP "-v" +.IP "--verbose" +.RS 4 +.IP "log to console" +.RE +.IP "-o" +.IP "--once" +.RS 4 +.IP "only run one pass of daemon" +.RE +.PD +.RE + + +.SH DOCUMENTATION +.LP +More in depth documentation in regards to +.BI swift-container-auditor +and also about Openstack-Swift as a whole can be found at +.BI http://swift.openstack.org/index.html + +.SH FILES +.IP "\fI/usr/share/doc/swift-account/container-server.conf-sample\fR" 0 +Sample configuration file for swift-container services + +.IP "\fI/etc/init.d/swift-container-auditor\fR" 0 +Container auditor init.d script + + + +.SH "SEE ALSO" +.BR container-server.conf(5) diff --git a/doc/manpages/swift-container-replicator.1 b/doc/manpages/swift-container-replicator.1 new file mode 100644 index 0000000000..f1f7a11cd1 --- /dev/null +++ b/doc/manpages/swift-container-replicator.1 @@ -0,0 +1,79 @@ +.\" +.\" Author: Joao Marcelo Martins or +.\" Copyright (c) 2010-2011 OpenStack, LLC. +.\" +.\" 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. +.\" +.TH swift-container-replicator 1 "8/26/2011" "Linux" "OpenStack Swift" + +.SH NAME +.LP +.B swift-container-replicator +\- Openstack-swift container replicator + +.SH SYNOPSIS +.LP +.B swift-container-replicator +[CONFIG] [-h|--help] [-v|--verbose] [-o|--once] + +.SH DESCRIPTION +.PP +Replication is designed to keep the system in a consistent state in the face of +temporary error conditions like network outages or drive failures. The replication +processes compare local data with each remote copy to ensure they all contain the +latest version. Container replication uses a combination of hashes and shared high +water marks to quickly compare subsections of each partition. +.PP +Replication updates are push based. Container replication push missing records over +HTTP or rsync whole database files. The replicator also ensures that data is removed +from the system. When an container item is deleted a tombstone is set as the latest +version of the item. The replicator will see the tombstone and ensure that the item +is removed from the entire system. + +The options are as follows: + +.RS 4 +.PD 0 +.IP "-v" +.IP "--verbose" +.RS 4 +.IP "log to console" +.RE +.IP "-o" +.IP "--once" +.RS 4 +.IP "only run one pass of daemon" +.RE +.PD +.RE + + +.SH DOCUMENTATION +.LP +More in depth documentation in regards to +.BI swift-container-replicator +and also about Openstack-Swift as a whole can be found at +.BI http://swift.openstack.org/index.html + +.SH FILES +.IP "\fI/usr/share/doc/swift-container/container-server.conf-sample\fR" 0 +Sample configuration file for swift-container services + +.IP "\fI/etc/init.d/swift-container-replicator\fR" 0 +Container replicator init.d script + + + +.SH "SEE ALSO" +.BR container-server.conf(5) diff --git a/doc/manpages/swift-container-server.1 b/doc/manpages/swift-container-server.1 new file mode 100644 index 0000000000..bbbab8230e --- /dev/null +++ b/doc/manpages/swift-container-server.1 @@ -0,0 +1,57 @@ +.\" +.\" Author: Joao Marcelo Martins or +.\" Copyright (c) 2010-2011 OpenStack, LLC. +.\" +.\" 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. +.\" +.TH swift-container-server 1 "8/26/2011" "Linux" "OpenStack Swift" + +.SH NAME +.LP +.B swift-container-server +\- Openstack-swift container server + +.SH SYNOPSIS +.LP +.B swift-container-server +[CONFIG] [-h|--help] [-v|--verbose] + +.SH DESCRIPTION +.PP +The Container Server's primary job is to handle listings of objects. It doesn't know +where those objects are, just what objects are in a specific container. The listings +are stored as sqlite database files, and replicated across the cluster similar to how +objects are. Statistics are also tracked that include the total number of objects, and +total storage usage for that container. + +.SH DOCUMENTATION +.LP +More in depth documentation in regards to +.BI swift-container-server +and also about Openstack-Swift as a whole can be found at +.BI http://swift.openstack.org/index.html +and +.BI http://docs.openstack.org + +.SH FILES +.IP "\fI/usr/share/doc/swift-container/container-server.conf-sample\fR" 0 +Sample configuration file for swift-container server +.IP "\fI/etc/init.d/swift-container\fR" 0 +Container server init.d script + + +.LP + +.SH "SEE ALSO" +.BR container-server.conf(5) diff --git a/doc/manpages/swift-container-sync.1 b/doc/manpages/swift-container-sync.1 new file mode 100644 index 0000000000..6f393e0237 --- /dev/null +++ b/doc/manpages/swift-container-sync.1 @@ -0,0 +1,60 @@ +.\" +.\" Author: Joao Marcelo Martins or +.\" Copyright (c) 2010-2011 OpenStack, LLC. +.\" +.\" 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. +.\" +.TH swift-container-sync 1 "8/26/2011" "Linux" "OpenStack Swift" + +.SH NAME +.LP +.B swift-container-sync +\- Openstack-swift container sync + +.SH SYNOPSIS +.LP +.B swift-container-sync +[CONFIG] [-h|--help] [-v|--verbose] [-o|--once] + +.SH DESCRIPTION +.PP +Swift has a feature where all the contents of a container can be mirrored to +another container through background synchronization. Swift cluster operators +configure their cluster to allow/accept sync requests to/from other clusters, +and the user specifies where to sync their container to along with a secret +synchronization key. +.PP +The swift-container-sync does the job of sending updates to the remote container. +This is done by scanning the local devices for container databases and checking +for x-container-sync-to and x-container-sync-key metadata values. If they exist, +newer rows since the last sync will trigger PUTs or DELETEs to the other container. + +.SH DOCUMENTATION +.LP +More in depth documentation in regards to +.BI swift-container-sync +and also about Openstack-Swift as a whole can be found at +.BI http://swift.openstack.org/overview_container_sync.html +and +.BI http://docs.openstack.org + +.SH FILES +.IP "\fI/usr/share/doc/swift-container/container-server.conf-sample\fR" 0 +Sample configuration file for swift-container server + + +.LP + +.SH "SEE ALSO" +.BR container-server.conf(5) diff --git a/doc/manpages/swift-container-updater.1 b/doc/manpages/swift-container-updater.1 new file mode 100644 index 0000000000..978638ced5 --- /dev/null +++ b/doc/manpages/swift-container-updater.1 @@ -0,0 +1,80 @@ +.\" +.\" Author: Joao Marcelo Martins or +.\" Copyright (c) 2010-2011 OpenStack, LLC. +.\" +.\" 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. +.\" +.TH swift-container-updater 1 "8/26/2011" "Linux" "OpenStack Swift" + +.SH NAME +.LP +.B swift-container-updater +\- Openstack-swift container updater + +.SH SYNOPSIS +.LP +.B swift-container-updater +[CONFIG] [-h|--help] [-v|--verbose] [-o|--once] + +.SH DESCRIPTION +.PP +The container updater is responsible for updating container information in the account database. +It will walk the container path in the system looking for container DBs and sending updates +to the account server as needed as it goes along. + +There are times when account data can not be immediately updated. This usually occurs +during failure scenarios or periods of high load. This is where an eventual consistency +window will most likely come in to play. + +In practice, the consistency window is only as large as the frequency at which +the updater runs and may not even be noticed as the proxy server will route +listing requests to the first account server which responds. The server under +load may not be the one that serves subsequent listing requests – one of the other +two replicas may handle the listing. + +The options are as follows: + +.RS 4 +.PD 0 +.IP "-v" +.IP "--verbose" +.RS 4 +.IP "log to console" +.RE +.IP "-o" +.IP "--once" +.RS 4 +.IP "only run one pass of daemon" +.RE +.PD +.RE + +.SH DOCUMENTATION +.LP +More in depth documentation in regards to +.BI swift-container-updater +and also about Openstack-Swift as a whole can be found at +.BI http://swift.openstack.org/index.html + +.SH FILES +.IP "\fI/usr/share/doc/swift-container/container-server.conf-sample\fR" 0 +Sample configuration file for swift-container services + +.IP "\fI/etc/init.d/swift-container-updater\fR" 0 +Container updater init.d script + + + +.SH "SEE ALSO" +.BR container-server.conf(5) diff --git a/doc/manpages/swift-dispersion-populate.1 b/doc/manpages/swift-dispersion-populate.1 new file mode 100644 index 0000000000..27188cef1b --- /dev/null +++ b/doc/manpages/swift-dispersion-populate.1 @@ -0,0 +1,95 @@ +.\" +.\" Author: Joao Marcelo Martins or +.\" Copyright (c) 2010-2011 OpenStack, LLC. +.\" +.\" 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. +.\" +.TH swift-dispersion-populate 1 "8/26/2011" "Linux" "OpenStack Swift" + +.SH NAME +.LP +.B swift-dispersion-populate +\- Openstack-swift dispersion populate + +.SH SYNOPSIS +.LP +.B swift-dispersion-populate + +.SH DESCRIPTION +.PP +This is one of the swift-dispersion utilities that is used to evaluate the +overall cluster health. This is accomplished by checking if a set of +deliberately distributed containers and objects are currently in their +proper places within the cluster. + +.PP +For instance, a common deployment has three replicas of each object. +The health of that object can be measured by checking if each replica +is in its proper place. If only 2 of the 3 is in place the object's health +can be said to be at 66.66%, where 100% would be perfect. + +.PP +We need to place the containers and objects throughout the system so +that they are on distinct partitions. The \fBswift-dispersion-populate\fR tool +does this by making up random container and object names until they fall +on distinct partitions. Last, and repeatedly for the life of the cluster, +we need to run the \fBswift-dispersion-report\fR tool to check the health of each +of these containers and objects. + +.PP +These tools need direct access to the entire cluster and to the ring files. +Installing them on a proxy server will probably do or a box used for swift +administration purposes that also contains the common swift packages and ring. +Both \fBswift-dispersion-populate\fR and \fBswift-dispersion-report\fR use the +same configuration file, /etc/swift/dispersion.conf . The account used by these +tool should be a dedicated account for the dispersion stats and also have admin +privileges. + +.SH CONFIGURATION +.PD 0 +Example \fI/etc/swift/dispersion.conf\fR: + +.RS 3 +.IP "[dispersion]" +.IP "auth_url = https://127.0.0.1:443/auth/v1.0" +.IP "auth_user = dpstats:dpstats" +.IP "auth_key = dpstats" +.IP "swift_dir = /etc/swift" +.IP "# dispersion_coverage = 1" +.IP "# retries = 5" +.IP "# concurrency = 25" +.RE +.PD + .SH EXAMPLE +.PP +.PD 0 +$ swift-dispersion-populate +.RS 1 +.IP "Created 2621 containers for dispersion reporting, 38s, 0 retries" +.IP "Created 2621 objects for dispersion reporting, 27s, 0 retries" +.RE +.PD + +.SH DOCUMENTATION +.LP +More in depth documentation about the swift-dispersion utilities and +also Openstack-Swift as a whole can be found at +.BI http://swift.openstack.org/admin_guide.html#cluster-health +and +.BI http://swift.openstack.org + + +.SH "SEE ALSO" +.BR swift-dispersion-report(1), +.BR dispersion.conf (5) diff --git a/doc/manpages/swift-dispersion-report.1 b/doc/manpages/swift-dispersion-report.1 new file mode 100644 index 0000000000..a02fc948ec --- /dev/null +++ b/doc/manpages/swift-dispersion-report.1 @@ -0,0 +1,99 @@ +.\" +.\" Author: Joao Marcelo Martins or +.\" Copyright (c) 2010-2011 OpenStack, LLC. +.\" +.\" 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. +.\" +.TH swift-dispersion-report 1 "8/26/2011" "Linux" "OpenStack Swift" + +.SH NAME +.LP +.B swift-dispersion-report +\- Openstack-swift dispersion report + +.SH SYNOPSIS +.LP +.B swift-dispersion-report + +.SH DESCRIPTION +.PP +This is one of the swift-dispersion utilities that is used to evaluate the +overall cluster health. This is accomplished by checking if a set of +deliberately distributed containers and objects are currently in their +proper places within the cluster. + +.PP +For instance, a common deployment has three replicas of each object. +The health of that object can be measured by checking if each replica +is in its proper place. If only 2 of the 3 is in place the object's health +can be said to be at 66.66%, where 100% would be perfect. + +.PP +Once the \fBswift-dispersion-populate\fR has been used to populate the +dispersion account, one should run the \fBswift-dispersion-report\fR tool +repeatedly for the life of the cluster, in order to check the health of each +of these containers and objects. + +.PP +These tools need direct access to the entire cluster and to the ring files. +Installing them on a proxy server will probably do or a box used for swift +administration purposes that also contains the common swift packages and ring. +Both \fBswift-dispersion-populate\fR and \fBswift-dispersion-report\fR use the +same configuration file, /etc/swift/dispersion.conf . The account used by these +tool should be a dedicated account for the dispersion stats and also have admin +privileges. + +.SH CONFIGURATION +.PD 0 +Example \fI/etc/swift/dispersion.conf\fR: + +.RS 3 +.IP "[dispersion]" +.IP "auth_url = https://127.0.0.1:443/auth/v1.0" +.IP "auth_user = dpstats:dpstats" +.IP "auth_key = dpstats" +.IP "swift_dir = /etc/swift" +.IP "# dispersion_coverage = 1" +.IP "# retries = 5" +.IP "# concurrency = 25" +.RE +.PD + .SH EXAMPLE +.PP +.PD 0 +$ swift-dispersion-report + +.RS 1 +.IP "Queried 2622 containers for dispersion reporting, 31s, 0 retries" +.IP "100.00% of container copies found (7866 of 7866)" +.IP "Sample represents 1.00% of the container partition space" + +.IP "Queried 2621 objects for dispersion reporting, 22s, 0 retries" +.IP "100.00% of object copies found (7863 of 7863)" +.IP "Sample represents 1.00% of the object partition space" +.RE +.PD + +.SH DOCUMENTATION +.LP +More in depth documentation about the swift-dispersion utilities and +also Openstack-Swift as a whole can be found at +.BI http://swift.openstack.org/admin_guide.html#cluster-health +and +.BI http://swift.openstack.org + + +.SH "SEE ALSO" +.BR swift-dispersion-populate(1), +.BR dispersion.conf (5) diff --git a/doc/manpages/swift-get-nodes.1 b/doc/manpages/swift-get-nodes.1 new file mode 100644 index 0000000000..d9409c58f5 --- /dev/null +++ b/doc/manpages/swift-get-nodes.1 @@ -0,0 +1,78 @@ +.\" +.\" Author: Joao Marcelo Martins or +.\" Copyright (c) 2010-2011 OpenStack, LLC. +.\" +.\" 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. +.\" +.TH swift-get-nodes 1 "8/26/2011" "Linux" "OpenStack Swift" + +.SH NAME +.LP +.B swift-get-nodes +\- Openstack-swift get-nodes tool + +.SH SYNOPSIS +.LP +.B swift-get-nodes +\ [] [] + +.SH DESCRIPTION +.PP +The swift-get-nodes tool can be used to find out the location where +a particular account, container or object item is located within the +swift cluster nodes. For example, if you have the account hash and a container +name that belongs to that account, you can use swift-get-nodes to lookup +where the container resides by using the container ring. + +.RS 0 +.IP "\fIExample:\fR" +.RE + +.RS 4 +.PD 0 +.IP "$ swift-get-nodes /etc/swift/account.ring.gz MyAccount-12ac01446be2" + +.PD 0 +.IP "Account MyAccount-12ac01446be2" +.IP "Container None" +.IP "Object None" + +.IP "Partition 221082" +.IP "Hash d7e6ba68cfdce0f0e4ca7890e46cacce" + +.IP "Server:Port Device 172.24.24.29:6002 sdd" +.IP "Server:Port Device 172.24.24.27:6002 sdr" +.IP "Server:Port Device 172.24.24.32:6002 sde" +.IP "Server:Port Device 172.24.24.26:6002 sdv [Handoff]" + +.IP "curl -I -XHEAD http://172.24.24.29:6002/sdd/221082/MyAccount-12ac01446be2" +.IP "curl -I -XHEAD http://172.24.24.27:6002/sdr/221082/MyAccount-12ac01446be2" +.IP "curl -I -XHEAD http://172.24.24.32:6002/sde/221082/MyAccount-12ac01446be2" +.IP "curl -I -XHEAD http://172.24.24.26:6002/sdv/221082/MyAccount-12ac01446be2 # [Handoff]" + +.IP "ssh 172.24.24.29 ls -lah /srv/node/sdd/accounts/221082/cce/d7e6ba68cfdce0f0e4ca7890e46cacce/ " +.IP "ssh 172.24.24.27 ls -lah /srv/node/sdr/accounts/221082/cce/d7e6ba68cfdce0f0e4ca7890e46cacce/" .IP "ssh 172.24.24.32 ls -lah /srv/node/sde/accounts/221082/cce/d7e6ba68cfdce0f0e4ca7890e46cacce/" .IP "ssh 172.24.24.26 ls -lah /srv/node/sdv/accounts/221082/cce/d7e6ba68cfdce0f0e4ca7890e46cacce/ # [Handoff] " +.PD +.RE + +.SH DOCUMENTATION +.LP +More documentation about Openstack-Swift can be found at +.BI http://swift.openstack.org/index.html + + + +.SH "SEE ALSO" +.BR swift-object-info(1), +.BR swift-ring-builder(1) diff --git a/doc/manpages/swift-init.1 b/doc/manpages/swift-init.1 new file mode 100644 index 0000000000..4dac048b2e --- /dev/null +++ b/doc/manpages/swift-init.1 @@ -0,0 +1,120 @@ +.\" +.\" Author: Joao Marcelo Martins or +.\" Copyright (c) 2010-2011 OpenStack, LLC. +.\" +.\" 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. +.\" +.TH swift-init 1 "8/26/2011" "Linux" "OpenStack Swift" + +.SH NAME +.LP +.B swift-init +\- Openstack-swift swift-init tool + +.SH SYNOPSIS +.LP +.B swift-init + [ ...] [options] + +.SH DESCRIPTION +.PP +The swift-init tool can be used to initialize all swift daemons available as part of +openstack-swift. Instead of calling individual init.d scripts for each +swift daemon, one can just use swift-init. With swift-init you can initialize +just one swift service, such as the "proxy", or a combination of them. The tool also +allows one to use the keywords such as "all", "main" and "rest" for the argument. + + +\fBServers:\fR + +.PD 0 +.RS 4 +.IP "\fIproxy\fR" "4" +.IP " - Initializes the swift proxy daemon" +.RE + +.RS 4 +.IP "\fIobject\fR, \fIobject-replicator\fR, \fIobject-auditor\fR, \fIobject-updater\fR" +.IP " - Initialize the swift object daemons above" +.RE + +.RS 4 +.IP "\fIcontainer\fR, \fIcontainer-update\fR, \fIcontainer-replicator\fR, \fIcontainer-auditor\fR" +.IP " - Initialize the swift container daemons above" +.RE + +.RS 4 +.IP "\fIaccount\fR, \fIaccount-auditor\fR, \fIaccount-reaper\fR, \fIaccount-replicator\fR" +.IP " - Initializes the swift account daemons above" +.RE + +.RS 4 +.IP "\fIall\fR" +.IP " - Initializes \fBall\fR the swift daemons" +.RE + +.RS 4 +.IP "\fImain\fR" +.IP " - Initializes all the \fBmain\fR swift daemons " +.IP " (proxy, container, account and object servers)" +.RE + +.RS 4 +.IP "\fIrest\fR" +.IP " - Initializes all the other \fBswift background daemons\fR such as" +.IP " (updater, replicator, auditor, reaper)" +.RE +.PD + + +\fBCommands:\fR + +.RS 4 +.PD 0 +.IP "\fIforce-reload\fR: \t\t alias for reload" +.IP "\fIno-daemon\fR: \t\t start a server interactively" +.IP "\fIno-wait\fR: \t\t\t spawn server and return immediately" +.IP "\fIonce\fR: \t\t\t start server and run one pass on supporting daemons" +.IP "\fIreload\fR: \t\t\t graceful shutdown then restart on supporting servers" +.IP "\fIrestart\fR: \t\t\t stops then restarts server" +.IP "\fIshutdown\fR: \t\t allow current requests to finish on supporting servers" +.IP "\fIstart\fR: \t\t\t starts a server" +.IP "\fIstatus\fR: \t\t\t display status of tracked pids for server" +.IP "\fIstop\fR: \t\t\t stops a server" +.PD +.RE + + + +\fBOptions:\fR +.RS 4 +.PD 0 +.IP "-h, --help \t\t\t show this help message and exit" +.IP "-v, --verbose \t\t\t display verbose output" +.IP "-w, --no-wait \t\t\t won't wait for server to start before returning +.IP "-o, --once \t\t\t only run one pass of daemon +.IP "-n, --no-daemon \t\t start server interactively +.IP "-g, --graceful \t\t send SIGHUP to supporting servers +.IP "-c N, --config-num=N \t send command to the Nth server only +.PD +.RE + + +.SH DOCUMENTATION +.LP +More documentation about Openstack-Swift can be found at +.BI http://swift.openstack.org/index.html + + + diff --git a/doc/manpages/swift-object-auditor.1 b/doc/manpages/swift-object-auditor.1 new file mode 100644 index 0000000000..47aef4e53a --- /dev/null +++ b/doc/manpages/swift-object-auditor.1 @@ -0,0 +1,78 @@ +.\" +.\" Author: Joao Marcelo Martins or +.\" Copyright (c) 2010-2011 OpenStack, LLC. +.\" +.\" 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. +.\" +.TH swift-object-auditor 1 "8/26/2011" "Linux" "OpenStack Swift" + +.SH NAME +.LP +.B swift-object-auditor +\- Openstack-swift object auditor + +.SH SYNOPSIS +.LP +.B swift-object-auditor +[CONFIG] [-h|--help] [-v|--verbose] [-o|--once] [-z|--zero_byte_fps] + +.SH DESCRIPTION +.PP +The object auditor crawls the local object system checking the integrity of objects. +If corruption is found (in the case of bit rot, for example), the file is +quarantined, and replication will replace the bad file from another replica. + +The options are as follows: + +.RS 4 +.PD 0 +.IP "-v" +.IP "--verbose" +.RS 4 +.IP "log to console" +.RE + +.IP "-o" +.IP "--once" +.RS 4 +.IP "only run one pass of daemon" +.RE + +.IP "-z ZERO_BYTE_FPS" +.IP "--zero_byte_fps=ZERO_BYTE_FPS" +.RS 4 +.IP "Audit only zero byte files at specified files/sec" +.RE +.PD +.RE + + +.SH DOCUMENTATION +.LP +More in depth documentation in regards to +.BI swift-object-auditor +and also about Openstack-Swift as a whole can be found at +.BI http://swift.openstack.org/index.html + +.SH FILES +.IP "\fI/usr/share/doc/swift-object/object-server.conf-sample\fR" 0 +Sample configuration file for swift-object services + +.IP "\fI/etc/init.d/swift-object-auditor\fR" 0 +Object auditor init.d script + + + +.SH "SEE ALSO" +.BR object-server.conf(5) diff --git a/doc/manpages/swift-object-info.1 b/doc/manpages/swift-object-info.1 new file mode 100644 index 0000000000..fe38638b03 --- /dev/null +++ b/doc/manpages/swift-object-info.1 @@ -0,0 +1,55 @@ +.\" +.\" Author: Joao Marcelo Martins or +.\" Copyright (c) 2010-2011 OpenStack, LLC. +.\" +.\" 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. +.\" +.TH swift-object-info 1 "8/26/2011" "Linux" "OpenStack Swift" + +.SH NAME +.LP +.B swift-object-info +\- Openstack-swift object-info tool + +.SH SYNOPSIS +.LP +.B swift-object-info +[OBJECT_FILE] + +.SH DESCRIPTION +.PP +This is a very simple swift tool that allows a swiftop engineer to retrieve +information about an object that is located on the storage node. One calls +the tool with a given object file as it is stored on the storage node system. +It will then return several information about that object such as; + +.PD 0 +.IP "- Account it belongs to" +.IP "- Container " +.IP "- Object hash " +.IP "- Location on the ring " +.IP "- Content Type " +.IP "- timestamp " +.IP "- Etag " +.IP "- Content Length " +.IP "- User Metadata " +.PD + +.SH DOCUMENTATION +.LP +More documentation about Openstack-Swift can be found at +.BI http://swift.openstack.org/index.html + +.SH "SEE ALSO" +.BR swift-get-nodes(1), diff --git a/doc/manpages/swift-object-replicator.1 b/doc/manpages/swift-object-replicator.1 new file mode 100644 index 0000000000..12e1a33ab1 --- /dev/null +++ b/doc/manpages/swift-object-replicator.1 @@ -0,0 +1,79 @@ +.\" +.\" Author: Joao Marcelo Martins or +.\" Copyright (c) 2010-2011 OpenStack, LLC. +.\" +.\" 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. +.\" +.TH swift-object-replicator 1 "8/26/2011" "Linux" "OpenStack Swift" + +.SH NAME +.LP +.B swift-object-replicator +\- Openstack-swift object replicator + +.SH SYNOPSIS +.LP +.B swift-object-replicator +[CONFIG] [-h|--help] [-v|--verbose] [-o|--once] + +.SH DESCRIPTION +.PP +Replication is designed to keep the system in a consistent state in the face of +temporary error conditions like network outages or drive failures. The replication +processes compare local data with each remote copy to ensure they all contain the +latest version. Object replication uses a hash list to quickly compare subsections +of each partition. +.PP +Replication updates are push based. For object replication, updating is just a matter +of rsyncing files to the peer. The replicator also ensures that data is removed +from the system. When an object item is deleted a tombstone is set as the latest +version of the item. The replicator will see the tombstone and ensure that the item +is removed from the entire system. + +The options are as follows: + +.RS 4 +.PD 0 +.IP "-v" +.IP "--verbose" +.RS 4 +.IP "log to console" +.RE +.IP "-o" +.IP "--once" +.RS 4 +.IP "only run one pass of daemon" +.RE +.PD +.RE + + +.SH DOCUMENTATION +.LP +More in depth documentation in regards to +.BI swift-object-replicator +and also about Openstack-Swift as a whole can be found at +.BI http://swift.openstack.org/index.html + +.SH FILES +.IP "\fI/usr/share/doc/swift-object/object-server.conf-sample\fR" 0 +Sample configuration file for swift-object services + +.IP "\fI/etc/init.d/swift-object-replicator\fR" 0 +Object replicator init.d script + + + +.SH "SEE ALSO" +.BR object-server.conf(5) diff --git a/doc/manpages/swift-object-server.1 b/doc/manpages/swift-object-server.1 new file mode 100644 index 0000000000..5d720156b5 --- /dev/null +++ b/doc/manpages/swift-object-server.1 @@ -0,0 +1,63 @@ +.\" +.\" Author: Joao Marcelo Martins or +.\" Copyright (c) 2010-2011 OpenStack, LLC. +.\" +.\" 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. +.\" +.TH swift-object-server 1 "8/26/2011" "Linux" "OpenStack Swift" + +.SH NAME +.LP +.B swift-object-server +\- Openstack-swift object server. + +.SH SYNOPSIS +.LP +.B swift-object-server +[CONFIG] [-h|--help] [-v|--verbose] + +.SH DESCRIPTION +.PP +The Object Server is a very simple blob storage server that can store, retrieve +and delete objects stored on local devices. Objects are stored as binary files +on the filesystem with metadata stored in the file's extended attributes (xattrs). +This requires that the underlying filesystem choice for object servers support +xattrs on files. Some filesystems, like ext3, have xattrs turned off by default. +Each object is stored using a path derived from the object name's hash and the operation's +timestamp. Last write always wins, and ensures that the latest object version will be +served. A deletion is also treated as a version of the file (a 0 byte file ending with +".ts", which stands for tombstone). This ensures that deleted files are replicated +correctly and older versions don't magically reappear due to failure scenarios. + +.SH DOCUMENTATION +.LP +More in depth documentation in regards to +.BI swift-object-server +and also about Openstack-Swift as a whole can be found at +.BI http://swift.openstack.org/index.html +and +.BI http://docs.openstack.org + +.SH FILES +.IP "\fI/usr/share/doc/swift-object/object-server.conf-sample\fR" 0 +Sample configuration file for swift-object server +.IP "\fI/usr/share/doc/swift-object/rsyncd.conf-sample\fR" 0 +Sample rsyncd configuration file for usage with swift-object +.IP "\fI/etc/init.d/swift-object\fR" 0 +Object server init.d script + + + +.SH "SEE ALSO" +.BR object-server.conf(5) diff --git a/doc/manpages/swift-object-updater.1 b/doc/manpages/swift-object-updater.1 new file mode 100644 index 0000000000..d361a761a9 --- /dev/null +++ b/doc/manpages/swift-object-updater.1 @@ -0,0 +1,86 @@ +.\" +.\" Author: Joao Marcelo Martins or +.\" Copyright (c) 2010-2011 OpenStack, LLC. +.\" +.\" 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. +.\" +.TH swift-object-updater 1 "8/26/2011" "Linux" "OpenStack Swift" + +.SH NAME +.LP +.B swift-object-updater +\- Openstack-swift object updater + +.SH SYNOPSIS +.LP +.B swift-object-updater +[CONFIG] [-h|--help] [-v|--verbose] [-o|--once] + +.SH DESCRIPTION +.PP +The object updater is responsible for updating object information in container listings. +It will check to see if there are any locally queued updates on the filesystem of each +devices, what is also known as async pending file(s), walk each one and update the +container listing. + +For example, suppose a container server is under load and a new object is put +into the system. The object will be immediately available for reads as soon as +the proxy server responds to the client with success. However, the object +server has not been able to update the object listing in the container server. +Therefore, the update would be queued locally for a later update. Container listings, +therefore, may not immediately contain the object. This is where an eventual consistency +window will most likely come in to play. + +In practice, the consistency window is only as large as the frequency at which +the updater runs and may not even be noticed as the proxy server will route +listing requests to the first container server which responds. The server under +load may not be the one that serves subsequent listing requests – one of the other +two replicas may handle the listing. + +The options are as follows: + +.RS 4 +.PD 0 +.IP "-v" +.IP "--verbose" +.RS 4 +.IP "log to console" +.RE +.IP "-o" +.IP "--once" +.RS 4 +.IP "only run one pass of daemon" +.RE +.PD +.RE + + +.SH DOCUMENTATION +.LP +More in depth documentation in regards to +.BI swift-object-updater +and also about Openstack-Swift as a whole can be found at +.BI http://swift.openstack.org/index.html + +.SH FILES +.IP "\fI/usr/share/doc/swift-object/object-server.conf-sample\fR" 0 +Sample configuration file for swift-object services + +.IP "\fI/etc/init.d/swift-object-updater\fR" 0 +Object updater init.d script + + + +.SH "SEE ALSO" +.BR object-server.conf(5) diff --git a/doc/manpages/swift-proxy-server.1 b/doc/manpages/swift-proxy-server.1 new file mode 100644 index 0000000000..5533e7b532 --- /dev/null +++ b/doc/manpages/swift-proxy-server.1 @@ -0,0 +1,58 @@ +.\" +.\" Author: Joao Marcelo Martins or +.\" Copyright (c) 2010-2011 OpenStack, LLC. +.\" +.\" 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. +.\" +.TH swift-proxy-server 1 "8/26/2011" "Linux" "OpenStack Swift" + +.SH NAME +.LP +.B swift-proxy-server +\- Openstack-swift proxy server. + +.SH SYNOPSIS +.LP +.B swift-proxy-server +[CONFIG] [-h|--help] [-v|--verbose] + +.SH DESCRIPTION +.PP +The Swift Proxy Server is responsible for tying together the rest of the Swift architecture. +For each request, it will look up the location of the account, container, or object in the +ring and route the request accordingly. The public API is also exposed through the Proxy +Server. A large number of failures are also handled in the Proxy Server. For example, +if a server is unavailable for an object PUT, it will ask the ring for a handoff server +and route there instead. When objects are streamed to or from an object server, they are +streamed directly through the proxy server to or from the user the proxy server does +not spool them. + +.SH DOCUMENTATION +.LP +More in depth documentation in regards to +.BI swift-proxy-server +and also about Openstack-Swift as a whole can be found at +.BI http://swift.openstack.org/index.html + +.\" One may need to change the path below if +.SH FILES +.IP "\fI/usr/share/doc/swift-proxy/proxy-server.conf-sample\fR" 0 +Sample configuration file for swift-proxy services +.IP "\fI/etc/init.d/swift-proxy\fR" 0 +Proxy server init.d script + + + +.SH "SEE ALSO" +.BR proxy-server.conf(5) diff --git a/doc/manpages/swift-recon.1 b/doc/manpages/swift-recon.1 new file mode 100644 index 0000000000..fabe4cf4d8 --- /dev/null +++ b/doc/manpages/swift-recon.1 @@ -0,0 +1,109 @@ +.\" +.\" Author: Joao Marcelo Martins or +.\" Copyright (c) 2010-2011 OpenStack, LLC. +.\" +.\" 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. +.\" +.TH swift-recon 1 "8/26/2011" "Linux" "OpenStack Swift" + +.SH NAME +.LP +.B swift-recon +\- Openstack-swift recon middleware cli tool + +.SH SYNOPSIS +.LP +.B swift-recon +\ [-v] [--suppress] [-a] [-r] [-u] [-d] [-l] [--objmd5] + +.SH DESCRIPTION +.PP +The swift-recon cli tool can be used to retrieve various metrics and telemetry information about +a cluster that has been collected by the swift-recon middleware. + +In order to make use of the swift-recon middleware, update the object-server.conf file and +enable the recon middleware by adding a pipeline entry and setting its option(s). You can view +more information in the example section below. + + +.SH OPTIONS +.RS 0 +.PD 1 +.IP "\fB-h, --help\fR" +show this help message and exit +.IP "\fB-v, --verbose\fR" +Print verbose information +.IP "\fB--suppress\fR" +Suppress most connection related errors +.IP "\fB-a, --async\fR" +Get async stats +.IP "\fB-r, --replication\fR" +Get replication stats +.IP "\fB-u, --unmounted\fR" +Check cluster for unmounted devices +.IP "\fB-d, --diskusage\fR" +Get disk usage stats +.IP "\fB-l, --loadstats\fR" +Get cluster load average stats +.IP "\fB-q, --quarantined\fR" +Get cluster quarantine stats +.IP "\fB--objmd5\fR" +Get md5sums of object.ring.gz and compare to local copy +.IP "\fB--all\fR" +Perform all checks. Equivalent to -arudlq --objmd5 +.IP "\fB-z ZONE, --zone=ZONE\fR" +Only query servers in specified zone +.IP "\fB--swiftdir=PATH\fR" +Default = /etc/swift +.PD +.RE + + + +.SH EXAMPLE +.LP +.PD 0 +.RS 0 +.IP "ubuntu:~$ swift-recon -q --zone 3" +.IP "===============================================================================" +.IP "[2011-10-18 19:36:00] Checking quarantine dirs on 1 hosts... " +.IP "[Quarantined objects] low: 4, high: 4, avg: 4, total: 4 " +.IP "[Quarantined accounts] low: 0, high: 0, avg: 0, total: 0 " +.IP "[Quarantined containers] low: 0, high: 0, avg: 0, total: 0 " +.IP "===============================================================================" +.RE + +.RS 0 +Finally if you also wish to track asynchronous pending’s you will need to setup a +cronjob to run the swift-recon-cron script periodically: + +.IP "*/5 * * * * swift /usr/bin/swift-recon-cron /etc/swift/object-server.conf" +.RE + + + + +.SH DOCUMENTATION +.LP +More documentation about Openstack-Swift can be found at +.BI http://swift.openstack.org/index.html +Also more specific documentation about swift-recon can be found at +.BI http://swift.openstack.org/admin_guide.html#cluster-telemetry-and-monitoring + + + +.SH "SEE ALSO" +.BR object-server.conf(5), + + diff --git a/doc/manpages/swift-ring-builder.1 b/doc/manpages/swift-ring-builder.1 new file mode 100644 index 0000000000..c8433e8ddf --- /dev/null +++ b/doc/manpages/swift-ring-builder.1 @@ -0,0 +1,209 @@ +.\" +.\" Author: Joao Marcelo Martins or +.\" Copyright (c) 2010-2011 OpenStack, LLC. +.\" +.\" 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. +.\" +.TH swift-ring-builder 1 "8/26/2011" "Linux" "OpenStack Swift" + +.SH NAME +.LP +.B swift-ring-builder +\- Openstack-swift ring builder + +.SH SYNOPSIS +.LP +.B swift-ring-builder + <...> + +.SH DESCRIPTION +.PP +The swift-ring-builder utility is used to create, search and manipulate +the swift storage ring. The ring-builder assigns partitions to devices and +writes an optimized Python structure to a gzipped, pickled file on disk for +shipping out to the servers. The server processes just check the modification +time of the file occasionally and reload their in-memory copies of the ring +structure as needed. Because of how the ring-builder manages changes to the +ring, using a slightly older ring usually just means one of the three replicas +for a subset of the partitions will be incorrect, which can be easily worked around. +.PP +The ring-builder also keeps its own builder file with the ring information and +additional data required to build future rings. It is very important to keep +multiple backup copies of these builder files. One option is to copy the +builder files out to every server while copying the ring files themselves. +Another is to upload the builder files into the cluster itself. Complete loss +of a builder file will mean creating a new ring from scratch, nearly all +partitions will end up assigned to different devices, and therefore nearly all +data stored will have to be replicated to new locations. So, recovery from a +builder file loss is possible, but data will definitely be unreachable for an +extended time. + + +.SH SEARCH +.PD 0 + +.IP "\fB\fR" +.RS 5 +.IP "Can be of the form:" +.IP "dz-:/_" + +.IP "Any part is optional, but you must include at least one, examples:" + +.RS 3 +.IP "d74 Matches the device id 74" +.IP "z1 Matches devices in zone 1" +.IP "z1-1.2.3.4 Matches devices in zone 1 with the ip 1.2.3.4" +.IP "1.2.3.4 Matches devices in any zone with the ip 1.2.3.4" +.IP "z1:5678 Matches devices in zone 1 using port 5678" +.IP ":5678 Matches devices that use port 5678" +.IP "/sdb1 Matches devices with the device name sdb1" +.IP "_shiny Matches devices with shiny in the meta data" +.IP "_'snet: 5.6.7.8' Matches devices with snet: 5.6.7.8 in the meta data" +.IP "[::1] Matches devices in any zone with the ip ::1" +.IP "z1-[::1]:5678 Matches devices in zone 1 with ip ::1 and port 5678" +.RE + +Most specific example: + +.RS 3 +d74z1-1.2.3.4:5678/sdb1_"snet: 5.6.7.8" +.RE + +Nerd explanation: + +.RS 3 +.IP "All items require their single character prefix except the ip, in which case the - is optional unless the device id or zone is also included." +.RE +.RE +.PD + + +.SH COMMANDS + +.PD 0 + + +.IP "\fB\fR" +.RS 5 +Shows information about the ring and the devices within. +.RE + + +.IP "\fBsearch\fR " +.RS 5 +Shows information about matching devices. +.RE + + +.IP "\fBadd\fR z-:/_" +.RS 5 +Adds a device to the ring with the given information. No partitions will be +assigned to the new device until after running 'rebalance'. This is so you +can make multiple device changes and rebalance them all just once. +.RE + + +.IP "\fBcreate\fR " +.RS 5 +Creates with 2^ partitions and . + is number of hours to restrict moving a partition more than once. +.RE + + +.IP "\fBlist_parts\fR [] .." +.RS 5 +Returns a 2 column list of all the partitions that are assigned to any of +the devices matching the search values given. The first column is the +assigned partition number and the second column is the number of device +matches for that partition. The list is ordered from most number of matches +to least. If there are a lot of devices to match against, this command +could take a while to run. +.RE + + +.IP "\fBrebalence\fR" +.RS 5 +Attempts to rebalance the ring by reassigning partitions that haven't been recently reassigned. +.RE + + +.IP "\fBremove\fR " +.RS 5 +Removes the device(s) from the ring. This should normally just be used for +a device that has failed. For a device you wish to decommission, it's best +to set its weight to 0, wait for it to drain all its data, then use this +remove command. This will not take effect until after running 'rebalance'. +This is so you can make multiple device changes and rebalance them all just once. +.RE + + +.IP "\fBset_info\fR :/_" +.RS 5 +Resets the device's information. This information isn't used to assign +partitions, so you can use 'write_ring' afterward to rewrite the current +ring with the newer device information. Any of the parts are optional +in the final :/_ parameter; just give what you +want to change. For instance set_info d74 _"snet: 5.6.7.8" would just +update the meta data for device id 74. +.RE + + +.IP "\fBset_min_part_hours\fR " +.RS 5 +Changes the to the given . This should be set to +however long a full replication/update cycle takes. We're working on a way +to determine this more easily than scanning logs. +.RE + + +.IP "\fBset_weight\fR " +.RS 5 +Resets the device's weight. No partitions will be reassigned to or from the +device until after running 'rebalance'. This is so you can make multiple +device changes and rebalance them all just once. +.RE + + +.IP "\fBvalidate\fR" +.RS 5 +Just runs the validation routines on the ring. +.RE + + +.IP "\fBwrite_ring\fR" +.RS 5 +Just rewrites the distributable ring file. This is done automatically after +a successful rebalance, so really this is only useful after one or more 'set_info' +calls when no rebalance is needed but you want to send out the new device information. +.RE + + +\fBQuick list:\fR add create list_parts rebalance remove search set_info + set_min_part_hours set_weight validate write_ring + +\fBExit codes:\fR 0 = ring changed, 1 = ring did not change, 2 = error +.PD + + + +.SH DOCUMENTATION +.LP +More in depth documentation about the swift ring and also Openstack-Swift as a +whole can be found at +.BI http://swift.openstack.org/overview_ring.html, +.BI http://swift.openstack.org/admin_guide.html#managing-the-rings +and +.BI http://swift.openstack.org + + diff --git a/doc/manpages/swift.1 b/doc/manpages/swift.1 new file mode 100644 index 0000000000..9e86dd1601 --- /dev/null +++ b/doc/manpages/swift.1 @@ -0,0 +1,121 @@ +.\" +.\" Author: Joao Marcelo Martins or +.\" Copyright (c) 2010-2011 OpenStack, LLC. +.\" +.\" 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. +.\" +.TH swift 1 "8/26/2011" "Linux" "OpenStack Swift" + +.SH NAME +.LP +.B swift +\- Openstack-swift swift tool + +.SH SYNOPSIS +.LP +.B swift +[options] [args] + +.SH DESCRIPTION +.PP +The swift tool is a command line interface script for communicating with +an openstack-swift object storage environment. It allows one to perform +several types of operations. + +.SH COMMANDS +.PP + +\fBstat\fR [\fIcontainer\fR] [\fIobject\fR] +.RS 4 +Displays information for the account, container, or object depending on the args given (if any). +.RE + +\fBlist\fR [\fIcommand-options\fR] [\fIcontainer\fR] +.RS 4 +Lists the containers for the account or the objects for a container. The -p or --prefix is an option that will only list items beginning +with that prefix. The -d or --delimiter is option (for container listings only) +that will roll up items with the given delimiter (see Cloud Files general +documentation for what this means). +.RE + +\fBupload\fR [\fIcommand-options\fR] container file_or_directory [\fIfile_or_directory\fR] [...] +.RS 4 +Uploads to the given container the files and directories specified by the +remaining args. The -c or --changed is an option that will only upload files +that have changed since the last upload. The -S or --segment-size +and --leave-segments are options as well (see --help for more). +.RE + +\fBpost\fR [\fIcommand-options\fR] [\fIcontainer\fR] [\fIobject\fR] +.RS 4 +Updates meta information for the account, container, or object depending +on the args given. If the container is not found, it will be created +automatically; but this is not true for accounts and objects. Containers +also allow the -r (or --read-acl) and -w (or --write-acl) options. The -m +or --meta option is allowed on all and used to define the user meta data +items to set in the form Name:Value. This option can be repeated. +\fBExample\fR: post -m Color:Blue -m Size:Large +.RE + + \fBdownload\fR [\fIcommand-options\fR] [\fIcontainer\fR] [\fIobject\fR] [\fIobject\fR] [...] +.RS 4 +Downloads everything in the account (with --all), or everything in a +container, or a list of objects depending on the args given. For a single +object download, you may use the -o [--output] option to +redirect the output to a specific file or if "-" then just redirect to stdout. +.RE + +\fBdelete\fR [\fIcommand-options\fR] [\fIcontainer\fR] [\fIobject\fR] [\fIobject\fR] [...] +.RS 4 +Deletes everything in the account (with --all), or everything in a container, +or a list of objects depending on the args given. Segments of manifest objects +will be deleted as well, unless you specify the --leave-segments option. +.RE + + .SH OPTIONS +.PD 0 +.IP "--version Show program's version number and exit" +.IP "-h, --help Show this help message and exit" +.IP "-s, --snet Use SERVICENET internal network" +.IP "-v, --verbose Print more info" +.IP "-q, --quiet Suppress status output" +.IP "-A AUTH, --auth=AUTH URL for obtaining an auth token " +.IP "-U USER, --user=USER User name for obtaining an auth token" +.IP "-K KEY, --key=KEY Key for obtaining an auth token" +.PD + + .SH EXAMPLE +.PP +swift -A https://127.0.0.1:443/auth/v1.0 -U swiftops:swiftops -K swiftops stat + +.RS 2 +.PD 0 +.IP "Account: AUTH_43b42dae-dc0b-4a4b-ac55-97de614d6e6e" +.IP "Containers: 1" +.IP "Objects: 1" +.IP "Bytes: 1124" +.IP "Accept-Ranges: bytes" +.IP "X-Trans-Id: txb21186a9eef64ed295a1e95896a0fc72" +.PD +.RE + + +.SH DOCUMENTATION +.LP +More in depth documentation about Openstack-Swift as a whole can be found at +.BI http://swift.openstack.org + + +.LP +