From 2d4346bfe1007f7475dc9d0ff4190cc2df511ae8 Mon Sep 17 00:00:00 2001 From: Harshavardhana Date: Thu, 31 May 2018 20:46:01 -0700 Subject: [PATCH] Add 'mc admin' complete guide (#2456) Fixes #2428 --- cmd/admin-heal.go | 4 +- cmd/admin-info.go | 8 +- cmd/admin-service-restart.go | 4 +- cmd/admin-service-status.go | 2 +- cmd/admin-service-stop.go | 4 +- cmd/admin-service.go | 4 +- docs/minio-admin-complete-guide.md | 303 ++++++++++++++++++++++++++++ docs/minio-client-complete-guide.md | 15 +- 8 files changed, 327 insertions(+), 17 deletions(-) create mode 100644 docs/minio-admin-complete-guide.md diff --git a/cmd/admin-heal.go b/cmd/admin-heal.go index c7bbf6a7..9dfe73e9 100644 --- a/cmd/admin-heal.go +++ b/cmd/admin-heal.go @@ -1,5 +1,5 @@ /* - * Minio Client (C) 2017-2018 Minio, Inc. + * Minio Client (C) 2017, 2018 Minio, Inc. * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. @@ -43,7 +43,7 @@ var adminHealFlags = []cli.Flag{ var adminHealCmd = cli.Command{ Name: "heal", - Usage: "Start an object heal operation", + Usage: "Heal disks, buckets and objects on Minio server", Action: mainAdminHeal, Before: setGlobalsFromContext, Flags: append(adminHealFlags, globalFlags...), diff --git a/cmd/admin-info.go b/cmd/admin-info.go index 120facb1..88c81db6 100644 --- a/cmd/admin-info.go +++ b/cmd/admin-info.go @@ -1,5 +1,5 @@ /* - * Minio Client (C) 2016,2017,2018 Minio, Inc. + * Minio Client (C) 2016, 2017, 2018 Minio, Inc. * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. @@ -36,7 +36,7 @@ var ( var adminInfoCmd = cli.Command{ Name: "info", - Usage: "Get Minio server information", + Usage: "Display Minio server information", Action: mainAdminInfo, Before: setGlobalsFromContext, Flags: append(adminInfoFlags, globalFlags...), @@ -159,9 +159,9 @@ func (u infoMessage) String() (msg string) { humanize.IBytes(u.ServerInfo.ConnStats.TotalInputBytes), humanize.IBytes(u.ServerInfo.ConnStats.TotalOutputBytes)) // Get storage information - msg += fmt.Sprintf(" Storage : Used %s\n", humanize.IBytes(u.StorageInfo.Used)) + msg += fmt.Sprintf(" Storage : Used %s", humanize.IBytes(u.StorageInfo.Used)) if v, ok := u.ServerInfo.StorageInfo.Backend.(xlBackend); ok { - msg += fmt.Sprintf(" Disks : %s, %s\n", console.Colorize("Info", v.OnlineDisks), + msg += fmt.Sprintf("\n Disks : %s, %s\n", console.Colorize("Info", v.OnlineDisks), console.Colorize("InfoFail", v.OfflineDisks)) } return diff --git a/cmd/admin-service-restart.go b/cmd/admin-service-restart.go index c798c343..4fe581c6 100644 --- a/cmd/admin-service-restart.go +++ b/cmd/admin-service-restart.go @@ -28,7 +28,7 @@ import ( var adminServiceRestartCmd = cli.Command{ Name: "restart", - Usage: "Restart a minio server", + Usage: "Restart Minio server", Action: mainAdminServiceRestart, Before: setGlobalsFromContext, Flags: globalFlags, @@ -42,7 +42,7 @@ FLAGS: {{range .VisibleFlags}}{{.}} {{end}} EXAMPLES: - 1. Restart a Minio server represented by its alias 'play'. + 1. Restart Minio server represented by its alias 'play'. $ {{.HelpName}} play/ `, diff --git a/cmd/admin-service-status.go b/cmd/admin-service-status.go index 588e23b2..391e5192 100644 --- a/cmd/admin-service-status.go +++ b/cmd/admin-service-status.go @@ -34,7 +34,7 @@ var ( var adminServiceStatusCmd = cli.Command{ Name: "status", - Usage: "Get the status of a Minio server", + Usage: "Get the status of Minio server", Action: mainAdminServiceStatus, Before: setGlobalsFromContext, Flags: append(adminServiceStatusFlags, globalFlags...), diff --git a/cmd/admin-service-stop.go b/cmd/admin-service-stop.go index 68bb28eb..80568af0 100644 --- a/cmd/admin-service-stop.go +++ b/cmd/admin-service-stop.go @@ -28,7 +28,7 @@ import ( var adminServiceStopCmd = cli.Command{ Name: "stop", - Usage: "Stop a minio server", + Usage: "Stop Minio server", Action: mainAdminServiceStop, Before: setGlobalsFromContext, Flags: globalFlags, @@ -42,7 +42,7 @@ FLAGS: {{range .VisibleFlags}}{{.}} {{end}} EXAMPLES: - 1. Stop a Minio server represented by its alias 'play'. + 1. Stop Minio server represented by its alias 'play'. $ {{.HelpName}} play/ `, diff --git a/cmd/admin-service.go b/cmd/admin-service.go index 246e1425..c4940ede 100644 --- a/cmd/admin-service.go +++ b/cmd/admin-service.go @@ -1,5 +1,5 @@ /* - * Minio Client (C) 2016, 2017 Minio, Inc. + * Minio Client (C) 2016, 2017, 2018 Minio, Inc. * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. @@ -20,7 +20,7 @@ import "github.com/minio/cli" var adminServiceCmd = cli.Command{ Name: "service", - Usage: "Control servers", + Usage: "Stop, restart or get status of Minio server", Action: mainAdminService, Before: setGlobalsFromContext, Flags: globalFlags, diff --git a/docs/minio-admin-complete-guide.md b/docs/minio-admin-complete-guide.md new file mode 100644 index 00000000..8290a43b --- /dev/null +++ b/docs/minio-admin-complete-guide.md @@ -0,0 +1,303 @@ +# Minio Admin Complete Guide [![Slack](https://slack.minio.io/slack?type=svg)](https://slack.minio.io) + +Minio Client (mc) provides `admin` sub-command to perform administrative tasks on your Minio deployments. + +```sh +service Stop, restart or get the status of Minio servers +info Display Minio server information +heal Heal disks, buckets and objects on Minio server +``` + +## 1. Download Minio Client +### Docker Stable +``` +docker pull minio/mc +docker run minio/mc admin info play +``` + +### Docker Edge +``` +docker pull minio/mc:edge +docker run minio/mc:edge admin info play +``` + +### Homebrew (macOS) +Install mc packages using [Homebrew](http://brew.sh/) + +```sh +brew install minio/stable/mc +mc --help +``` + +### Binary Download (GNU/Linux) +| Platform | Architecture | URL | +| ---------- | -------- |------| +|GNU/Linux|64-bit Intel|https://dl.minio.io/client/mc/release/linux-amd64/mc | + +```sh +chmod +x mc +./mc --help +``` + +### Binary Download (Microsoft Windows) +| Platform | Architecture | URL | +| ---------- | -------- |------| +|Microsoft Windows|64-bit Intel|https://dl.minio.io/client/mc/release/windows-amd64/mc.exe | + +```sh +mc.exe --help +``` + +### Install from Source +Source installation is intended only for developers and advanced users. `mc update` command does not support update notifications for source based installations. Please download official releases from https://minio.io/downloads/#minio-client. + +If you do not have a working Golang environment, please follow [How to install Golang](https://docs.minio.io/docs/how-to-install-golang). + +```sh +go get -d github.com/minio/mc +cd ${GOPATH}/src/github.com/minio/mc +make +``` + +## 2. Run Minio Client + +### GNU/Linux + +```sh +chmod +x mc +./mc --help +``` + +### macOS + +```sh +chmod 755 mc +./mc --help +``` + +### Microsoft Windows + +```sh +mc.exe --help +``` + +## 3. Add a Minio Storage Service +Minio server displays URL, access and secret keys. + +#### Usage + +```sh +mc config host add +``` + +Alias is simply a short name to your Minio service. Minio end-point, access and secret keys are supplied by your Minio service. Admin API uses "S3v4" signature and cannot be changed. + +```sh +mc config host add minio http://192.168.1.51:9000 BKIKJAA5BMMU2RHO6IBB V7f1CwQqAcwo80UEIJEjc5gVQUSSx5ohQ9GSrr12 +``` + +## 4. Test Your Setup +`mc` is pre-configured with https://play.minio.io:9000, aliased as "play". It is a hosted Minio server for testing and development purposes. + +*Example:* + +Get Minio server information from https://play.minio.io:9000 + +```sh +● play.minio.io:9000 + Uptime : online since 1 day ago + Version : 2018-05-28T04:31:38Z + Region : + SQS ARNs : + Stats : Incoming 82GiB, Outgoing 28GiB + Storage : Used 7.4GiB +``` + +## 5. Everyday Use +You may add shell aliases for info, healing. + +```sh +alias minfo='mc admin info' +alias mheal='mc admin heal' +``` + +## 6. Global Options + +### Option [--debug] +Debug option enables debug output to console. + +*Example: Display verbose debug output for `info` command.* + +```sh +mc admin --debug info play +mc: GET /minio/admin/v1/info HTTP/1.1 +Host: play.minio.io:9000 +User-Agent: Minio (linux; amd64) madmin-go/0.0.1 mc/2018-05-23T23:43:34Z +Authorization: AWS4-HMAC-SHA256 Credential=**REDACTED**/20180530/us-east-1/s3/aws4_request, SignedHeaders=host;x-amz-content-sha256;x-amz-date, Signature=**REDACTED** +X-Amz-Content-Sha256: UNSIGNED-PAYLOAD +X-Amz-Date: 20180530T001808Z +Accept-Encoding: gzip + +mc: HTTP/1.1 200 OK +Transfer-Encoding: chunked +Accept-Ranges: bytes +Content-Security-Policy: block-all-mixed-content +Content-Type: application/json +Date: Wed, 30 May 2018 00:18:08 GMT +Server: Minio/DEVELOPMENT.2018-05-28T04-31-38Z (linux; amd64) +Vary: Origin +X-Amz-Request-Id: 1533440573A63034 +X-Xss-Protection: "1; mode=block" + +mc: Response Time: 140.70112ms + +● play.minio.io:9000 + Uptime : online since 1 day ago + Version : 2018-05-28T04:31:38Z + Region : + SQS ARNs : + Stats : Incoming 82GiB, Outgoing 28GiB + Storage : Used 7.4GiB +``` + +### Option [--json] +JSON option enables parseable output in JSON format. + +*Example: Minio server information.* + +```sh +mc admin --json info play +{ + "status": "success", + "service": "on", + "address": "play.minio.io:9000", + "error": "", + "storage": { + "used": 7979370172, + "backend": { + "backendType": "FS" + } + }, + "network": { + "transferred": 90473434722, + "received": 30662519192 + }, + "server": { + "uptime": 157467244813288, + "version": "2018-05-28T04:31:38Z", + "commitID": "7d8c5ffb13334f4aec20a35bd2575bd7c740fb7a", + "region": "", + "sqsARN": [] + } +} +``` + +### Option [--no-color] +This option disables the color theme. It is useful for dumb terminals. + +### Option [--quiet] +Quiet option suppress chatty console output. + +### Option [--config-folder] +Use this option to set a custom config path. + +### Option [ --insecure] +Skip SSL certificate verification. + +## 7. Commands + +| | +|:---| +|[**service** - Start, stop or get the status of Minio server](#service) | +|[**info** - Display Minio server information](#info) | +|[**heal** - Heal disks, buckets and objects on Minio server](#heal) | + + +### Command `service` - Stop, restart or get status of Minio server +`service` command provides a way to restart, stop one or get the status of Minio servers (distributed cluster) + +```sh +NAME: + mc admin service - Stop, restart or get status of Minio server + +FLAGS: + --help, -h Show help. + +COMMANDS: + status Get the status of Minio server + restart Restart Minio server + stop Stop Minio server +``` + +*Example: Display service uptime for Minio server.* + +```sh +mc admin service status play +Uptime: 1 days 19 hours 57 minutes 39 seconds. +``` + +*Example: Restart remote minio service.* + +NOTE: `restart` and `stop` sub-commands are disruptive operations for your Minio service, any on-going API operations will be forcibly cancelled. So, it should be used only under certain circumstances. Please use it with caution. + +```sh +mc admin service restart play +Restarted `play` successfully. +``` + + +### Command `info` - Display Minio server information +`info` command displays server information of one or many Minio servers (under distributed cluster) + +```sh +NAME: + mc admin info - Get Minio server information + +FLAGS: + --help, -h Show help. +``` + +*Example: Display Minio server information.* + +```sh +● play.minio.io:9000 + Uptime : online since 1 day ago + Version : 2018-05-28T04:31:38Z + Region : + SQS ARNs : + Stats : Incoming 82GiB, Outgoing 28GiB + Storage : Used 8.2GiB +``` + + +### Command `heal` - Heal disks, buckets and objects on Minio server +`heal` command heals disks, missing buckets, objects on Minio server. NOTE: This command is only applicable for Minio erasure coded setup (standalone and distributed). + +```sh +NAME: + mc admin heal - Heal disks, buckets and objects on Minio server + +FLAGS: + --recursive, -r Heal recursively + --dry-run, -n Only inspect data, but do not mutate + --force-start, -f Force start a new heal sequence + --help, -h Show help. +``` + +*Example: Heal Minio cluster after replacing a fresh disk, recursively heal all buckets and objects, where 'myminio' is the Minio server alias.* + +```sh +mc admin heal -r myminio +``` + +*Example: Heal Minio cluster on a specific bucket recursively, where 'myminio' is the Minio server alias.* + +```sh +mc admin heal -r myminio/mybucket +``` + +*Example: Heal Minio cluster on a specific object prefix recursively, where 'myminio' is the Minio server alias.* + +```sh +mc admin heal -r myminio/mybucket/myobjectprefix +``` diff --git a/docs/minio-client-complete-guide.md b/docs/minio-client-complete-guide.md index e7e5a4f1..1cb26a04 100644 --- a/docs/minio-client-complete-guide.md +++ b/docs/minio-client-complete-guide.md @@ -17,6 +17,7 @@ rm Remove files and objects. events Manage object notifications. watch Watch for file and object events. policy Manage anonymous access to objects. +admin Manage Minio servers session Manage saved sessions for cp command. config Manage mc configuration file. update Check for a new software update. @@ -115,7 +116,7 @@ To add one or more Amazon S3 compatible hosts, please follow the instructions be mc config host add ``` -Alias is simply a short name to you cloud storage service. S3 end-point, access and secret keys are supplied by your cloud storage provider. API signature is an optional argument. By default, it is set to "S3v4". +Alias is simply a short name to your cloud storage service. S3 end-point, access and secret keys are supplied by your cloud storage provider. API signature is an optional argument. By default, it is set to "S3v4". ### Example - Minio Cloud Storage Minio server displays URL, access and secret keys. @@ -220,7 +221,7 @@ mc --json ls play ``` ### Option [--no-color] -This option disables the color theme. It useful for dumb terminals. +This option disables the color theme. It is useful for dumb terminals. ### Option [--quiet] Quiet option suppress chatty console output. @@ -266,6 +267,7 @@ mc ls play [2016-03-28 21:53:49 IST] 0B guestbucket/ [2016-04-08 20:58:18 IST] 0B mybucket/ ``` + ### Command `mb` - Make a Bucket `mb` command creates a new bucket on an object storage. On a filesystem, it behaves like `mkdir -p` command. Bucket is equivalent of a drive or mount point in filesystems and should not be treated as folders. Minio does not place any limits on the number of buckets created per user. @@ -298,7 +300,6 @@ Bucket created successfully ‘s3/mybucket’. ``` - ### Command `cat` - Concatenate Objects `cat` command concatenates contents of a file or object to another. You may also use it to simply display the contents to stdout @@ -327,6 +328,7 @@ Hello Minio!! mc cat --encrypt-key "play/mybucket=32byteslongsecretkeymustbegiven1" play/mybucket/myencryptedobject.txt Hello Minio!! ``` + ### Command `pipe` - Pipe to Object `pipe` command copies contents of stdin to a target. When no target is specified, it writes to stdout. @@ -395,6 +397,7 @@ mc cp --encrypt-key 'myminio1/mybucket=32byteslongsecretkeymustgenerate , mymini encryptedobject: 14 B / 14 B ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ 100.00 % 41 B/s 0 ``` Notice that two different aliases myminio1 and myminio2 are used for the same endpoint to provide the old secretkey and the newly rotated key. + ### Command `rm` - Remove Buckets and Objects Use `rm` command to remove file or bucket @@ -731,6 +734,10 @@ mc policy none play/mybucket/myphotos/2020/ Access permission for ‘play/mybucket/myphotos/2020/’ is set to 'none' ``` + +### Command `admin` - Manage Minio servers +Please visit [here](./minio-admin-complete-guide.md) for a more comprehensive admin guide. + ### Command `session` - Manage Sessions ``session`` command manages previously saved sessions for `cp` and `mirror` operations @@ -905,4 +912,4 @@ ETag : d41d8cd98f00b204e9800998ecf8427e Type : file Metadata : Content-Type: application/octet-stream -``` \ No newline at end of file +```