openstack/swift
Code Issues Proposed changes

changing config files to be on section 5 and also running spellchecks against all files

Browse Source 
"Also adding the new swift-recon and swift-ring-builder manpages to this set"
"Adding new manpages for configuration files and also making changes according to previous review suggestions"
"removing the Author line from the manpages according to suggestions"

Change-Id: I256d2b2851b55a379b59011894f214bf55ba7da9
This commit is contained in:
Marcelo Martins 2011-10-12 13:23:13 -05:00
parent 3b8e20d059
commit 0b0785e984
27 changed files with 3148 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

228
doc/manpages/account-server.conf.5 Normal file
View File

@ -0,0 +1,228 @@
.\"
.\" Author: Joao Marcelo Martins <marcelo.martins@rackspace.com> or <btorch@gmail.com>
.\" 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),

249
doc/manpages/container-server.conf.5 Normal file
View File

@ -0,0 +1,249 @@
.\"
.\" Author: Joao Marcelo Martins <marcelo.martins@rackspace.com> or <btorch@gmail.com>
.\" 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),

83
doc/manpages/dispersion.conf.5 Normal file
View File

@ -0,0 +1,83 @@
.\"
.\" Author: Joao Marcelo Martins <marcelo.martins@rackspace.com> or <btorch@gmail.com>
.\" 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)

261
doc/manpages/object-server.conf.5 Normal file
View File

@ -0,0 +1,261 @@
.\"
.\" Author: Joao Marcelo Martins <marcelo.martins@rackspace.com> or <btorch@gmail.com>
.\" 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),

448
doc/manpages/proxy-server.conf.5 Normal file
View File

@ -0,0 +1,448 @@
.\"
.\" Author: Joao Marcelo Martins <marcelo.martins@rackspace.com> or <btorch@gmail.com>
.\" 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_<account>_<user>\fR
Lastly, you need to list all the accounts/users you want here. The format is:
user_<account>_<user> = <key> [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]://<ip>:<port>/v1/<reseller_prefix>_<account>\fR where http or https depends
on whether cert_file is specified in the [DEFAULT] section, <ip> and <port> are based
on the [DEFAULT] section's bind_ip and bind_port (falling back to 127.0.0.1 and 8080),
<reseller_prefix> is from this section, and <account> is from the user_<account>_<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),

71
doc/manpages/swift-account-auditor.1 Normal file
View File

@ -0,0 +1,71 @@
.\"
.\" Author: Joao Marcelo Martins <marcelo.martins@rackspace.com> or <btorch@gmail.com>
.\" 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)

77
doc/manpages/swift-account-reaper.1 Normal file
View File

@ -0,0 +1,77 @@
.\"
.\" Author: Joao Marcelo Martins <marcelo.martins@rackspace.com> or <btorch@gmail.com>
.\" 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)

79
doc/manpages/swift-account-replicator.1 Normal file
View File

@ -0,0 +1,79 @@
.\"
.\" Author: Joao Marcelo Martins <marcelo.martins@rackspace.com> or <btorch@gmail.com>
.\" 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)

54
doc/manpages/swift-account-server.1 Normal file
View File

@ -0,0 +1,54 @@
.\"
.\" Author: Joao Marcelo Martins <marcelo.martins@rackspace.com> or <btorch@gmail.com>
.\" 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)

72
doc/manpages/swift-container-auditor.1 Normal file
View File

@ -0,0 +1,72 @@
.\"
.\" Author: Joao Marcelo Martins <marcelo.martins@rackspace.com> or <btorch@gmail.com>
.\" 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)

79
doc/manpages/swift-container-replicator.1 Normal file
View File

@ -0,0 +1,79 @@
.\"
.\" Author: Joao Marcelo Martins <marcelo.martins@rackspace.com> or <btorch@gmail.com>
.\" 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)

57
doc/manpages/swift-container-server.1 Normal file
View File

@ -0,0 +1,57 @@
.\"
.\" Author: Joao Marcelo Martins <marcelo.martins@rackspace.com> or <btorch@gmail.com>
.\" 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)

60
doc/manpages/swift-container-sync.1 Normal file
View File

@ -0,0 +1,60 @@
.\"
.\" Author: Joao Marcelo Martins <marcelo.martins@rackspace.com> or <btorch@gmail.com>
.\" 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)

80
doc/manpages/swift-container-updater.1 Normal file
View File

@ -0,0 +1,80 @@
.\"
.\" Author: Joao Marcelo Martins <marcelo.martins@rackspace.com> or <btorch@gmail.com>
.\" 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)

95
doc/manpages/swift-dispersion-populate.1 Normal file
View File

@ -0,0 +1,95 @@
.\"
.\" Author: Joao Marcelo Martins <marcelo.martins@rackspace.com> or <btorch@gmail.com>
.\" 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)

99
doc/manpages/swift-dispersion-report.1 Normal file
View File

@ -0,0 +1,99 @@
.\"
.\" Author: Joao Marcelo Martins <marcelo.martins@rackspace.com> or <btorch@gmail.com>
.\" 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)

78
doc/manpages/swift-get-nodes.1 Normal file
View File

@ -0,0 +1,78 @@
.\"
.\" Author: Joao Marcelo Martins <marcelo.martins@rackspace.com> or <btorch@gmail.com>
.\" 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
\ <ring.gz> <account> [<container>] [<object>]
.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)

120
doc/manpages/swift-init.1 Normal file
View File

@ -0,0 +1,120 @@
.\"
.\" Author: Joao Marcelo Martins <marcelo.martins@rackspace.com> or <btorch@gmail.com>
.\" 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
<server> [<server> ...] <command> [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 <server> 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

78
doc/manpages/swift-object-auditor.1 Normal file
View File

@ -0,0 +1,78 @@
.\"
.\" Author: Joao Marcelo Martins <marcelo.martins@rackspace.com> or <btorch@gmail.com>
.\" 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)

55
doc/manpages/swift-object-info.1 Normal file
View File

@ -0,0 +1,55 @@
.\"
.\" Author: Joao Marcelo Martins <marcelo.martins@rackspace.com> or <btorch@gmail.com>
.\" 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),

79
doc/manpages/swift-object-replicator.1 Normal file
View File

@ -0,0 +1,79 @@
.\"
.\" Author: Joao Marcelo Martins <marcelo.martins@rackspace.com> or <btorch@gmail.com>
.\" 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)

63
doc/manpages/swift-object-server.1 Normal file
View File

@ -0,0 +1,63 @@
.\"
.\" Author: Joao Marcelo Martins <marcelo.martins@rackspace.com> or <btorch@gmail.com>
.\" 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)

86
doc/manpages/swift-object-updater.1 Normal file
View File

@ -0,0 +1,86 @@
.\"
.\" Author: Joao Marcelo Martins <marcelo.martins@rackspace.com> or <btorch@gmail.com>
.\" 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)

58
doc/manpages/swift-proxy-server.1 Normal file
View File

@ -0,0 +1,58 @@
.\"
.\" Author: Joao Marcelo Martins <marcelo.martins@rackspace.com> or <btorch@gmail.com>
.\" 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)

109
doc/manpages/swift-recon.1 Normal file
View File

@ -0,0 +1,109 @@
.\"
.\" Author: Joao Marcelo Martins <marcelo.martins@rackspace.com> or <btorch@gmail.com>
.\" 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),

209
doc/manpages/swift-ring-builder.1 Normal file
View File

@ -0,0 +1,209 @@
.\"
.\" Author: Joao Marcelo Martins <marcelo.martins@rackspace.com> or <btorch@gmail.com>
.\" 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
<builder_file> <commands> <arguments> <...>
.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<search-value>\fR"
.RS 5
.IP "Can be of the form:"
.IP "d<device_id>z<zone>-<ip>:<port>/<device_name>_<meta>"
.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<builder_file>\fR"
.RS 5
Shows information about the ring and the devices within.
.RE
.IP "\fBsearch\fR <search-value>"
.RS 5
Shows information about matching devices.
.RE
.IP "\fBadd\fR z<zone>-<ip>:<port>/<device_name>_<meta><wght>"
.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 <part_power> <replicas> <min_part_hours>"
.RS 5
Creates <builder_file> with 2^<part_power> partitions and <replicas>.
<min_part_hours> is number of hours to restrict moving a partition more than once.
.RE
.IP "\fBlist_parts\fR <search-value> [<search-value>] .."
.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 <search-value> "
.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 <search-value> <ip>:<port>/<device_name>_<meta>"
.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 <ip>:<port>/<device_name>_<meta> 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 <hours>"
.RS 5
Changes the <min_part_hours> to the given <hours>. 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 <search-value> <weight>"
.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

121
doc/manpages/swift.1 Normal file
View File

@ -0,0 +1,121 @@
.\"
.\" Author: Joao Marcelo Martins <marcelo.martins@rackspace.com> or <btorch@gmail.com>
.\" 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] <command> [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 <size> or --segment-size <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] <filename> 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