chef-server-ctl (executable) — chef-client Man Pages

# chef-server-ctl (executable)

The Chef server includes a command-line utility named chef-server-ctl. This command-line tool is used to start and stop individual services, reconfigure the Chef server, run chef-pedant, and then tail Chef server log files.

## backup-recover

The `backup-recover` subcommand is used to force the Chef server to attempt to become the backup server. This is the opposite of the `master-recover` subcommand.

Warning

If this command is run on both back-end servers, it will put the back-end cluster into a state where no server holds the DRBD resource.

This subcommand has the following syntax:

    $ chef-server-ctl backup-recover

## cleanse

The `cleanse` subcommand is used to re-set the Chef server to the state it was in before the first time the `reconfigure` subcommand is run to destroy all data, configuration files, and logs.

This subcommand has the following syntax:

    $ chef-server-ctl cleanse

## gather-logs

The `gather-logs` subcommand is used to gather the Chef server log files into a tarball that contains all of the important log files and system information.

This subcommand has the following syntax:

    $ chef-server-ctl gather-logs

## ha-status

The `ha-status` subcommand is used to check the status for services running in a High Availability topology. This command will verify the following:

> - The Keepalived daemon is enabled in the config
> - The DRBD process is enabled in the config
> - The underlying block device or logical volume for DRBD has been created and configured
> - The DRBD device exists
> - The current state of the server is `master` or `backup`; any migration processes have completed
> - The failover virtual IP address is correctly attached to only the `master` node
> - The DRBD state is correct based on the state of the server being `master` or `backup`
> - The DRBD mount point is correctly mounted to only the `master` node
> - The DRBD replication IP addresses are pingable
> - The `runit` status of the services are correct (up or down) based on the `master` or `backup` state of the server

This subcommand has the following syntax:

    $ chef-server-ctl ha-status

If this command runs successfully, it will return the following:

    $ [OK] all checks passed.

Otherwise it will print out a list of errors, similar to the following:

    ...
    [OK] nginx is running correctly, and I am master.
    [ERROR] redis_lb is not running.
    [OK] opscode-erchef is running correctly, and I am master.
    ...
    [ERROR] ERRORS WERE DETECTED.

For example:

    [OK] keepalived HA services enabled
    [OK] DRBD disk replication enabled
    [OK] DRBD partition /dev/opscode/drbd found
    [OK] DRBD device /dev/drbd0 found
    [OK] cluster status = master
    [OK] found VIP IP address and I am master
    [OK] found VRRP communications interface eth1
    [OK] my DRBD status is Connected/Primary/UpToDate and I am master
    [OK] my DRBD partition is mounted and I am master
    [OK] DRBD primary IP address pings
    [OK] DRBD secondary IP address pings
    ...
    [OK] all checks passed.

## help

The `help` subcommand is used to print a list of all available chef-server-ctl commands.

This subcommand has the following syntax:

    $ chef-server-ctl help

## install

The `install` subcommand is used to install premium features of the Chef server: Chef management console, Chef analytics, chef-client run reporting, high availability configurations, Chef push jobs, and Chef server replication.

Syntax

This subcommand has the following syntax:

    $ chef-server-ctl install name_of_premium_feature (options)

where `name_of_premium_feature` represents the command line value associated with the premium feature:

Options

This subcommand has the following options:

`--path PATH`
  Use to specify the location of a package. This option is not required when packages are downloaded from https://packagecloud.io/.

### Use Downloads

The `install` subcommand downloads packages from https://packagecloud.io/ by default. For systems that are not behind a firewall (and have connectivity to https://packagecloud.io/), these packages can be installed as described below.

Feature | Command
--- | ---
Chef Manage | Use Chef management console to manage data bags, attributes, run-lists, roles, environments, and cookbooks from a web user interface. (Front end machines only.) Run:
    $ chef-server-ctl install opscode-manage
then:
    $ opscode-manage-ctl reconfigure
and then:
    $ chef-server-ctl reconfigure
Chef Push Jobs | Use Chef push jobs to run jobs—an action or a command to be executed—against nodes independently of a chef-client run. Run:
    $ chef-server-ctl install opscode-push-jobs-server
then:
    $ opscode-push-jobs-server-ctl reconfigure
and then:
    $ chef-server-ctl reconfigure
Chef Replication | Use Chef replication to asynchronously distribute cookbook, environment, role, and data bag data from a single, primary Chef server to one (or more) replicas of that Chef server. Run:
    $ chef-server-ctl install chef-sync
and then:
    $ chef-sync-ctl reconfigure
and then:
    $ chef-server-ctl reconfigure
Reporting | Use Chef reporting to keep track of what happens during every chef-client runs across all of the infrastructure being managed by Chef. Run Chef reporting with Chef management console to view reports from a web user interface. (Front end machines only.) Run:
    $ chef-server-ctl install opscode-reporting
then:
    $ opscode-reporting-ctl reconfigure
and then:
    $ chef-server-ctl reconfigure

### Use Local Packages

The `install` subcommand downloads packages from https://packagecloud.io/ by default. For systems that are behind a firewall (and do not have connectivity to https://packagecloud.io/), these packages can be installed manually. First download the package that is appropriate for the platform and save it to a local path. Then run the `install` command using the `--path` option to specify the location for the package:

    $ chef-server-ctl install NAME_OF_PACKAGE --path /path/to/package

For example:

    $ chef-server-ctl install opscode-manage-1.6.2-1.el6.x86_64 --path /home/vagrant

## master-recover

The `master-recover` subcommand is used to force the Chef server to attempt to become the master server. This command is typically run in tandem with the `backup-recover` subcommand on the back-end peer, unless the back-end peer is no longer available.

This subcommand has the following syntax:

    $ chef-server-ctl master-recover

## org-create

The `org-create` subcommand is used to create an organization. (The validation key for the organization is returned to `STDOUT` when creating an organization using this command.)

Syntax

This subcommand has the following syntax:

    $ chef-server-ctl org-create ORG_NAME ORG_FULL_NAME (options)

Options

This subcommand has the following options:

`-a USER_NAME`, `--association_user USER_NAME`
  Use to associate a user with an organization and add them to the `admins` and `billing_admins` security groups.
`-f FILE_NAME`, `--filename FILE_NAME`
  Use to write the private key to a file instead of `STDOUT`.

Examples

    $ chef-server-ctl org-create prod Production

    $ chef-server-ctl org-create staging Staging -a chef-admin

    $ chef-server-ctl org-create dev Development -f /tmp/id-dev.key

## org-delete

The `org-delete` subcommand is used to delete an organization.

Syntax

This subcommand has the following syntax:

    $ chef-server-ctl org-delete ORG_NAME

Examples

    $ chef-server-ctl org-delete infra-testing-20140909

    $ chef-server-ctl org-delete pedant-testing-org

## org-list

The `org-list` subcommand is used to list all of the organizations currently present on the Chef server.

Syntax

This subcommand has the following syntax:

    $ chef-server-ctl org-list (options)

Options

This subcommand has the following options:

`-a`, `--all-orgs`
  Use to show all organizations.
`-w`, `--with-uri`
  Use to show the corresponding URIs.

## org-show

The `org-show` subcommand is used to show the details for an organization.

Syntax

This subcommand has the following syntax:

    $ chef-server-ctl org-show ORG_NAME

## org-user-add

The `org-user-add` subcommand is used to add a user to an organization.

Syntax

This subcommand has the following syntax:

    $ chef-server-ctl org-user-add ORG_NAME USER_NAME (options)

Options

This subcommand has the following options:

`--admin`
  Use to add the user to the `admins` group.

Examples

    $ chef-server-ctl org-user-add prod john_smith

    $ chef-server-ctl org-user-add preprod testmaster

    $ chef-server-ctl org-user-add dev grantmc --admin

## org-user-remove

The `org-user-remove` subcommand is used to remove a user from an organization.

Syntax

This subcommand has the following syntax:

    $ chef-server-ctl org-user-remove ORG_NAME USER_NAME

Examples

    $ chef-server-ctl org-user-remove prod john_smith

    $ chef-server-ctl org-user-remove prod testmaster

## password

Warning

This subcommand is currently disabled.

## reconfigure

The `reconfigure` subcommand is used when changes are made to the private-chef.rb file to reconfigure the server. When changes are made to the private-chef.rb file, they will not be applied to the Chef server configuration until after this command is run. This subcommand will also restart any services for which the `service_name['enabled']` setting is set to `true`.

This subcommand has the following syntax:

    $ chef-server-ctl reconfigure

## show-config

The `show-config` subcommand is used to view the configuration that will be generated by the `reconfigure` subcommand. This command is most useful in the early stages of a deployment to ensure that everything is built properly prior to installation.

This subcommand has the following syntax:

    $ chef-server-ctl show-config

## uninstall

The `uninstall` subcommand is used to remove the Chef server application, but without removing any of the data. This subcommand will shut down all services (including the `runit` process supervisor).

This subcommand has the following syntax:

    $ chef-server-ctl uninstall

Note

To revert the `uninstall` subcommand, run the `reconfigure` subcommand (because the `start` subcommand is disabled by the `uninstall` command).

## upgrade

The `upgrade` subcommand is used to upgrade the Chef server.

Syntax

This subcommand has the following syntax:

    $ chef-server-ctl upgrade (options)

Options

Note

Options for the `upgrade` subcommand may only be used when upgrading from Open Source Chef 11 to Chef server 12.

This subcommand has the following options:

`-d DIRECTORY`, `--chef11-data-dir DIRECTORY`
  The directory in which Open Source Chef 11 data is located. Default value: a temporary directory.
`-e DIRECTORY`, `--chef12-data-dir DIRECTORY`
  The directory in which Chef server 12 data is located. Default value: a temporary directory.
`-f FULL_NAME`, `--full-org-name FULL_NAME`
  The full name of the Chef server organization. A full organization name must begin with a non-white space character and must be between 1 and 1023 characters. For example: `Chef Software, Inc.`. If this option is not specified, the `upgrade` command will prompt for it.
`-h`, `--help`
  Use to show help for the `chef-server-ctl upgrade` subcommand.
`-k KEY`, `--key KEY`
  All users are assigned a public key. Use to write the public key to a file. Default value: `/etc/chef-server/admin.pem`.
`-o ORG_NAME`, `--org-name ORG_NAME`
  The name of the Chef server organization. An organization name must begin with a lower-case letter or digit, may only contain lower-case letters, digits, hyphens, and underscores, and must be between 1 and 255 characters. For example: `chef`. If this option is not specified, the `upgrade` command will prompt for it.
`-s URL`, `--chef11-server-url URL`
  The URL for the Open Source Chef or Enterprise Chef server, version 11. Default value: `https://localhost`.
`-t NUMBER`, `--upload-threads NUMBER`
  The number of threads to use when migrating cookbooks. Default value: `10`.
`-u USER`, `--user`
  Use to create a client as an admin client. This is required for any user to access Open Source Chef as an administrator.
`-x URL`, `--chef12-server-url URL`
  The URL for the Chef server, version 12. Default value: `https://localhost`.
`-y`, `--yes`
  Use to skip confirmation prompts during the upgrade process.

## user-create

The `user-create` subcommand is used to create a user.

Syntax

This subcommand has the following syntax:

    $ chef-server-ctl user-create USER_NAME FIRST_NAME [MIDDLE_NAME] LAST_NAME EMAIL PASSWORD (options)

Options

This subcommand has the following options:

`-f FILE_NAME`, `--filename FILE_NAME`
  Use to write the private key to a file instead of `STDOUT`.

Examples

    $ chef-server-ctl user-create john_smith John Smith john_smith@example.com insecure-passord

    $ chef-server-ctl user-create jane_doe Jane Doe jane_doe@example.com PaSSword -f /tmp/jane_doe.key

    $ chef-server-ctl user-create waldendude Henry David Thoreau waldendude@example.com excursions

## user-delete

The `user-delete` subcommand is used to delete a user.

Syntax

This subcommand has the following syntax:

    $ chef-server-ctl user-delete USER_NAME

Examples

    $ chef-server-ctl user-delete john_smith

    $ chef-server-ctl user-delete jane_doe

## user-edit

The `user-edit` subcommand is used to edit the details for a user. The data will be made available in the $EDITOR for editing.

Syntax

This subcommand has the following syntax:

    $ chef-server-ctl user-edit USER_NAME

Examples

    $ chef-server-ctl user-edit john_smith

    $ chef-server-ctl user-edit jane_doe

## user-list

The `user-list` subcommand is used to view a list of users.

Syntax

This subcommand has the following syntax:

    $ chef-server-ctl user-list (options)

Options

This subcommand has the following options:

`-w`, `--with-uri`
  Use to show the corresponding URIs.

## user-show

The `user-show` subcommand is used to show the details for a user.

Syntax

This subcommand has the following syntax:

    $ chef-server-ctl user-show USER_NAME (options)

Options

This subcommand has the following options:

`-l`, `--with-orgs`
  Use to show the corresponding organizations.

## Service Subcommands

The Chef server has a built in process supervisor, which ensures that all of the required services are in the appropriate state at any given time. The supervisor starts two processes per service.

### hup

The `hup` subcommand is used to send a `SIGHUP` to all services. This command can also be run for an individual service by specifying the name of the service in the command.

This subcommand has the following syntax:

    $ chef-server-ctl hup name_of_service

where `name_of_service` represents the name of any service that is listed after running the `service-list` subcommand.

### int

The `int` subcommand is used to send a `SIGINT` to all services. This command can also be run for an individual service by specifying the name of the service in the command.

This subcommand has the following syntax:

    $ chef-server-ctl int name_of_service

where `name_of_service` represents the name of any service that is listed after running the `service-list` subcommand.

### kill

The `kill` subcommand is used to send a `SIGKILL` to all services. This command can also be run for an individual service by specifying the name of the service in the command.

This subcommand has the following syntax:

    $ chef-server-ctl kill name_of_service

where `name_of_service` represents the name of any service that is listed after running the `service-list` subcommand.

### once

The supervisor for the Chef server is configured to restart any service that fails, unless that service has been asked to change its state. The `once` subcommand is used to tell the supervisor to not attempt to restart any service that fails.

This command is useful when troubleshooting configuration errors that prevent a service from starting. Run the `once` subcommand followed by the `status` subcommand to look for services in a down state and/or to identify which services are in trouble. This command can also be run for an individual service by specifying the name of the service in the command.

This subcommand has the following syntax:

    $ chef-server-ctl once name_of_service

where `name_of_service` represents the name of any service that is listed after running the `service-list` subcommand.

### restart

The `restart` subcommand is used to restart all services enabled on the Chef server or to restart an individual service by specifying the name of that service in the command.

Warning

When running the Chef server in a high availability configuration, restarting all services may trigger failover.

This subcommand has the following syntax:

    $ chef-server-ctl restart name_of_service

where `name_of_service` represents the name of any service that is listed after running the `service-list` subcommand. When a service is successfully restarted the output should be similar to:

    $ ok: run: service_name: (pid 12345) 1s

### service-list

The `service-list` subcommand is used to display a list of all available services. A service that is enabled is labeled with an asterisk (*).

This subcommand has the following syntax:

    $ chef-server-ctl service-list

### start

The `start` subcommand is used to start all services that are enabled in the Chef server. This command can also be run for an individual service by specifying the name of the service in the command.

This subcommand has the following syntax:

    $ chef-server-ctl start name_of_service

where `name_of_service` represents the name of any service that is listed after running the `service-list` subcommand. When a service is successfully started the output should be similar to:

    $ ok: run: service_name: (pid 12345) 1s

The supervisor for the Chef server is configured to wait seven seconds for a service to respond to a command from the supervisor. If you see output that references a timeout, it means that a signal has been sent to the process, but that the process has yet to actually comply. In general, processes that have timed out are not a big concern, unless they are failing to respond to the signals at all. If a process is not responding, use a command like the `kill` subcommand to stop the process, investigate the cause (if required), and then use the `start` subcommand to re-enable it.

### status

The `status` subcommand is used to show the status of all services available to the Chef server. The results will vary based on the configuration of a given server. This subcommand has the following syntax:

    $ chef-server-ctl status

and will return the status for all services. Status can be returned for individual services by specifying the name of the service as part of the command:

    $ chef-server-ctl status name_of_service

where `name_of_service` represents the name of any service that is listed after running the `service-list` subcommand.

When service status is requested, the output should be similar to:

    $ run: service_name: (pid 12345) 12345s; run: log: (pid 1234) 67890s

where

- `run:` is the state of the service (`run:` or `down:`)
- `service_name:` is the name of the service for which status is returned
- `(pid 12345)` is the process identifier
- `12345s` is the uptime of the service, in seconds

For example:

    $ down: opscode-erchef: (pid 35546) 10s

By default, runit will restart services automatically when the services fail. Therefore, runit may report the status of a service as `run:` even when there is an issue with that service. When investigating why a particular service is not running as it should be, look for the services with the shortest uptimes. For example, the list below indicates that the opscode-erchef should be investigated further:

    run: oc-id
    run: opscode-chef: (pid 4327) 13671s; run: log: (pid 4326) 13671s
    run: opscode-erchef: (pid 5383) 5s; run: log: (pid 4382) 13669s
    run: opscode-expander: (pid 4078) 13694s; run: log: (pid 4077) 13694s
    run: opscode-expander-reindexer: (pid 4130) 13692s; run: log: (pid 4114) 13692s

#### High Availability

On back-end servers in a High Availability topology, Keepalived is used by the clustering service to determine whether a service should be running. If the `status` subcommand is run against any of these nodes, a few things change:

- On the back-end node that is currently the backup server, it is normal to see only one running process: Keepalived
- On the back-end node that is currently the master server, it is normal to see all services running. It is also normal to see some services in a down state if the server, on reboot, did not attempt to start the services because Keepalived determines which services are restarted based on the state of the cluster

A sample status line for a service that is running on the master server in a High Availability topology:

    run: opscode-solr: (pid 25341) 239s, normally down; run: log: (pid 5700) 145308s

#### Log Files

A typical status line for a service that is running any of the Chef server front-end services is similar to the following:

    run: name_of_service: (pid 1486) 7819s; run: log: (pid 1485) 7819s

where:

- `run` describes the state in which the supervisor attempts to keep processes. This state is either `run` or `down`. If a service is in a `down` state, it should be stopped
- `name_of_service` is the service name, for example: `opscode-solr4`
- `(pid 1486) 7819s;` is the process identifier followed by the amount of time (in seconds) the service has been running
- `run: log: (pid 1485) 7819s` is the log process. It is typical for a log process to have a longer run time than a service; this is because the supervisor does not need to restart the log process in order to connect the supervised process

If the service is down, the status line will appear similar to the following:

    down: opscode-solr4: 3s, normally up; run: log: (pid 1485) 8526s

where

- `down` indicates that the service is in a down state
- `3s, normally up;` indicates that the service is normally in a run state and that the supervisor would attempt to restart this service after a reboot

### stop

The `stop` subcommand is used to stop all services enabled on the Chef server. This command can also be run for an individual service by specifying the name of the service in the command.

This subcommand has the following syntax:

    $ chef-server-ctl stop name_of_service

where `name_of_service` represents the name of any service that is listed after running the `service-list` subcommand. When a service is successfully stopped the output should be similar to:

    $ ok: diwb: service_name: 0s, normally up

For example:

    $ chef-server-ctl stop

will return something similar to:

    ok: down: nginx: 393s, normally up
    ok: down: opscode-chef: 391s, normally up
    ok: down: opscode-erchef: 391s, normally up
    ok: down: opscode-expander: 390s, normally up
    ok: down: opscode-expander-reindexer: 389s, normally up
    ok: down: opscode-solr4: 389s, normally up
    ok: down: postgresql: 388s, normally up
    ok: down: rabbitmq: 388s, normally up
    ok: down: redis_lb: 387s, normally up

### tail

The `tail` subcommand is used to follow all of the Chef server logs for all services. This command can also be run for an individual service by specifying the name of the service in the command.

This subcommand has the following syntax:

    $ chef-server-ctl tail name_of_service

where `name_of_service` represents the name of any service that is listed after running the `service-list` subcommand.

### term

The `term` subcommand is used to send a `SIGTERM` to all services. This command can also be run for an individual service by specifying the name of the service in the command.

This subcommand has the following syntax:

    $ chef-server-ctl term name_of_service

where `name_of_service` represents the name of any service that is listed after running the `service-list` subcommand.