.Dd March 24, 2020
.Dt S3DU 1
.Os
.Sh NAME
.Nm s3du
.Nd Utility for displaying AWS S3 bucket space usage
.Sh SYNOPSIS
.Nm
.Op Fl hV
.Op Fl Fl help
.Op Fl Fl version
.Nm
.Op Fl e Ar url
.Op Fl m Ar mode
.Op Fl o Ar versions
.Op Fl r Ar region
.Op Fl u Ar unit
.Op Ar bucket
.Sh DESCRIPTION
.Nm
is a utility for displaying space used in AWS S3 buckets.
If no
.Ar bucket
argument is passed,
.Nm
will display the space used by all discovered buckets.
.Nm
follows the default AWS credentials chain.
The options are as follows:
.Bl -tag -width indent
.It Fl h , Fl Fl help
Prints help information
.It Fl V , Fl Fl version
Prints version information
.It Fl e Ar url , Fl Fl endpoint Ns = Ns Ar url
Specify an endpoint to connect to in
.Cm s3
mode.
This allows for use of
.Nm
against S3 compatible storage such as MinIO.
This flag will only be present if
.Nm
was compiled with the
.Dq Cm s3
feature, and only affects the S3 mode.
.It Fl m Ar mode , Fl Fl mode Ns = Ns Ar mode
Specify which mode
.Nm
should run in.
Possibly values are:
.Dq Cm cloudwatch
and
.Dq Cm s3 .
.Cm cloudwatch
mode is cheaper at the cost of some accuracy while
.Cm s3
mode is more expensive but very accurate.
Defaults to
.Dq Cm cloudwatch .
.It Fl o Ar versions , Fl Fl object-versions Ns = Ns Ar versions
Specifies which object versions to sum the size of in
.Cm s3
mode.
Possible values are:
.Dq Cm all ,
.Dq Cm current ,
.Dq Cm multipart ,
and
.Dq Cm non-current .
This flag will only be present if
.Nm
was compiled with the
.Dq Cm s3
feature, and only affects the S3 mode.
Defaults to
.Dq Cm current .
.It Fl r Ar region , Fl Fl region Ns = Ns Ar region
Specify the AWS region to operate in.
The default value for the
.Ar region
is determined in the following order:
.Bl -enum
.It
The value of the
.Ev AWS_DEFAULT_REGION
environment variable.
.It
The value of the
.Ev AWS_REGION
environment variable.
This will override the value specified in
.Ev AWS_DEFAULT_REGION
if both environment variables are specified.
.It
Use the default AWS region
.Dq Cm us-east-1
if the environment variables failed to contain a valid region name or were not
specified.
.El
.It Fl u Ar unit , Fl Fl unit Ns = Ns Ar unit
Specify which
.Ar unit
to show bucket sizes in.
Possible values are
.Dq Cm binary ,
.Dq Cm bytes ,
and
.Dq Cm decimal .
.Ar binary
will show human friendly sizes using
.Dq SI
units (multiples of 1024).
.Ar bytes
will show the number of bytes used.
.Ar decimal
will show human friendly sizes using regular units (multiples of 1000).
Defaults to
.Dq Cm binary .
.El
.Sh ENVIRONMENT
.Nm
can also take its configuration from environment variables.
In the event that both command line arguments and environment variables are
specified, the command line arguments will be used.
.Bl -tag -width S3DU_OBJECT_VERSIONS
.It Ev AWS_DEFAULT_REGION
will be used as the default AWS region if no other region configuration is
specified.
.It Ev AWS_REGION
is equivalent to setting the
.Fl Fl region
option.
.It Ev S3DU_BUCKET
is equivalent to setting the
.Ar bucket
argument.
.It Ev S3DU_ENDPOINT
is equivalent to setting the
.Fl Fl endpoint
option.
This environment variable will only be present if
.Nm
has been compiled with the
.Dq Cm s3
feature.
.It Ev S3DU_MODE
is equivalent to setting the
.Fl Fl mode
option.
.It Ev S3DU_OBJECT_VERSIONS
is equivalent to setting the
.Fl Fl object-versions
option.
This environment variable will only be present if
.Nm
has been compiled with the
.Dq Cm s3
feature.
.It Ev S3DU_UNIT
is equivalent to setting the
.Fl Fl unit
option.
.El
.Sh FILES
.Bl -tag -width /usr/local/bin/s3du -compact
.It Pa /usr/local/bin/s3du
the
.Nm
binary.
.El
.Sh EXIT STATUS
The
.Nm
utility exits 0 on success, and >0 if an error occurs.
.Sh EXAMPLES
List all bucket sizes via CloudWatch in the default region:
.Pp
.Dl $ s3du
.Pp
Show a specific bucket size via CloudWatch in a non-default region:
.Pp
.Dl $ s3du --region=eu-west-1 my-bucket
.Pp
Show a specific bucket via S3 showing the size of only non-current objects:
.Pp
.Dl $ s3du --mode=s3 --object-versions=non-current my-bucket
.Pp
Show space used by all buckets in S3 compatible storage:
.Pp
.Dl $ s3du --mode=s3 --endpoint=https://s3-compatible.example.org
.Sh HISTORY
.Nm
was started around the beginning of 2020 and became feature complete around
March 2020 during the COVID-19
.Dq coronavirus
pandemic.
.Sh AUTHORS
.Nm
was developed by
.An David O'Rourke .
.Sh CAVEATS
While in-progress
.Ar multipart
uploads are not technically
.Dq object versions ,
selecting them for sizing is still covered under the
.Fl Fl object-versions
option as it is the most logical way to perform that operation.
.Pp
Usage of
.Nm
against S3 compatible storage only receives minimal testing as its main goal is
to support AWS S3.
.Sh BUGS
Please report bugs, issues, and feature requests to
.Lk https://github.com/phyber/s3du/issues
.Sh SECURITY CONSIDERATIONS
It is best to use
.Nm
with an AWS IAM user or role specifically created for
.Nm .
The policy applied to this user or role should grant the following permissions
for CloudWatch mode:
.Pp
.Dl cloudwatch:GetMetricStatistics
.Dl cloudwatch:ListMetrics
.Pp
and should grant the following permissions for S3 mode:
.Pp
.Dl s3:GetBucketLocation
.Dl s3:ListAllMyBuckets
.Dl s3:ListBucket