chef-server-ctl (executable)
Backup / Restore
Use the following commands to manage backups of Chef Infra Server data, and then to restore those backups.
backup
The backup
subcommand is used to back up all Chef Infra Server data.
This subcommand:
- Requires rsync to be installed on the Chef Infra Server before running the command
- Requires a
chef-server-ctl reconfigure
before running the command - Should not be run in a Chef Infra Server configuration with an external PostgreSQL database; use knife ec backup instead
- Puts the initial backup in the
/var/opt/chef-backup
directory as a tar.gz file; move this backup to a new location for safe keeping
Options
This subcommand has the following options:
-y
,--yes
Use to specify if the Chef Infra Server can go offline during tar.gz-based backups.
--pg-options
Use to specify and pass additional options PostgreSQL during backups. See the PostgreSQL documentation for more information.
-c
,--config-only
Backup the Chef Infra Server configuration without backing up data.
-t
,--timeout
Set the maximum amount of time in seconds to wait for shell commands (default 600). This option should be set to greater than 600 for backups taking longer than 10 minutes.
-h
,--help
Show help message.
Syntax
This subcommand has the following syntax:
chef-server-ctl backup
restore
The restore
subcommand is used to restore Chef Infra Server data from
a backup that was created by the backup
subcommand. This subcommand
may also be used to add Chef Infra Server data to a newly-installed
server. Do not run this command in a Chef Infra Server configuration that uses an external PostgreSQL database; use knife ec backup instead. This subcommand:
- Requires rsync installed on the Chef Infra Server before running the command
- Requires a
chef-server-ctl reconfigure
before running the command
Ideally, the restore server will have the same FQDN as the server that you backed up. If the restore server has a different FQDN, then:
- Replace the FQDN in the
/etc/opscode/chef-server.rb
. - Replace the FQDN in the
/etc/opscode/chef-server-running.json
. - Delete the old SSL certificate, key and
-ssl.conf
file from/var/opt/opscode/nginx/ca
. - If you use a CA-issued certificate instead of a self-signed certificate, copy the CA-issued certificate and key into
/var/opt/opscode/nginx/ca
. - Update the
/etc/chef/client.rb
file on each client to point to the new server FQDN. - Run
chef-server-ctl reconfigure
. - Run
chef-server-ctl restore
.
Options
This subcommand has the following options:
-c
,--cleanse
Use to remove all existing data on the Chef Infra Server; it will be replaced by the data in the backup archive.
-d DIRECTORY
,--staging-dir DIRECTORY
Use to specify that the path to an empty directory to be used during the restore process. This directory must have enough disk space to expand all data in the backup archive.
--pg-options
Use to specify and pass additional options PostgreSQL during backups. See the PostgreSQL documentation for more information.
-t
,--timeout
Set the maximum amount of time in seconds to wait for shell commands. Set to greater than 600 for backups that take longer than 10 minutes. Default: 600.
-h
,--help
Show help message.
Syntax
This subcommand has the following syntax:
chef-server-ctl restore PATH_TO_BACKUP (options)
Examples
chef-server-ctl restore /path/to/tar/archive.tar.gz
cleanse
The cleanse
subcommand is used to re-set the Chef Infra Server to the
state it was in prior to the first time the reconfigure
subcommand is
run. This command will destroy all data, configuration files, and logs.
The software that was put on-disk by the package installation will
remain; re-run chef-server-ctl reconfigure
to recreate the default
data and configuration files.
Options
This subcommand has the following options:
--with-external
Use to specify that Chef Infra Server data on an external PostgreSQL database should be removed.
Syntax
This subcommand has the following syntax:
chef-server-ctl cleanse
gather-logs
The gather-logs
subcommand is used to gather the Chef Infra 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
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
Infra Server: Chef management console and Chef Infra Client run
reporting, high availability configurations, and Chef
Infra Server replication.
Warning
chef-server-ctl install
command no longer works in the 12.5 (and
earlier) versions of the Chef Infra Server due to a change in how
packages are downloaded from Chef.Syntax
This subcommand has the following syntax:
chef-server-ctl install name_of_addon (options)
where name_of_addon
represents the command line value associated with
the add-on or 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://packages.chef.io/.
Use Downloads
The install
subcommand downloads packages from https://packages.chef.io by default.
For systems that are not behind a firewall (and have connectivity to https://packages.chef.io), these packages can be installed as described below.
Install add-ons
Install Chef Manage with:
sudo chef-server-ctl install chef-manage
Reconfigure the server
sudo chef-server-ctl reconfigure
Reconfigure add-ons
Reconfigure Chef Manage with:
sudo chef-manage-ctl reconfigure
Finally, accept the Chef License:
sudo chef-manage-ctl reconfigure --accept-license
Use Local Packages
Use the install
subcommand with the --path
option to install the Chef Manage (chef-manage
) add-on for Chef Infra Server.
sudo chef-server-ctl install PACKAGE_NAME --path /path/to/package/directory
For example:
sudo chef-server-ctl install chef-manage --path /root/packages
The chef-server-ctl
command will install the first chef-manage
package found in the /root/packages
directory.
Key Rotation
Use the following commands to manage public and private key rotation for users and clients.
add-client-key
Use the add-client-key
subcommand to add a client key.
Syntax
This subcommand has the following syntax:
chef-server-ctl add-client-key ORG_NAME CLIENT_NAME [--public-key-path PATH] [--expiration-date DATE] [--key-name NAME]
Warning
Options
This subcommand has the following options:
CLIENT_NAME
The name of the client that you wish to add a key for.
-e DATE
--expiration-date DATE
An ISO 8601 formatted string:
YYYY-MM-DDTHH:MM:SSZ
. For example:2013-12-24T21:00:00Z
. If not passed, expiration will default to infinity.-k NAME
--key-name NAME
String defining the name of your new key for this client. If not passed, it will default to the fingerprint of the public key.
ORG_NAME
The short name for the organization to which the client belongs.
-p PATH
--public-key-path PATH
The location to a file containing valid PKCS#1 public key to be added. If not passed, then the server will generate a new one for you and return the private key to STDOUT.
add-user-key
Use the add-user-key
subcommand to add a user key.
Syntax
This subcommand has the following syntax:
chef-server-ctl add-user-key USER_NAME [--public-key-path PATH] [--expiration-date DATE] [--key-name NAME]
Warning
Options
This subcommand has the following options:
-e DATE
--expiration-date DATE
An ISO 8601 formatted string:
YYYY-MM-DDTHH:MM:SSZ
. For example:2013-12-24T21:00:00Z
. If not passed, expiration will default to infinity.-k NAME
--key-name NAME
String defining the name of your new key for this user. If not passed, it will default to the fingerprint of the public key.
-p PATH
--public-key-path PATH
The location to a file containing valid PKCS#1 public key to be added. If not passed, then the server will generate a new one for you and return the private key to STDOUT.
USER_NAME
The user name for the user for which a key is added.
delete-client-key
Use the delete-client-key
subcommand to delete a client key.
Syntax
This subcommand has the following syntax:
chef-server-ctl delete-client-key ORG_NAME CLIENT_NAME KEY_NAME
Options
This subcommand has the following arguments:
ORG_NAME
The short name for the organization to which the client belongs.
CLIENT_NAME
The name of the client.
KEY_NAME
The unique name to be assigned to the key you wish to delete.
delete-user-key
Use the delete-user-key
subcommand to delete a user key.
Syntax
This subcommand has the following syntax:
chef-server-ctl delete-user-key USER_NAME KEY_NAME
Warning
Options
This subcommand has the following arguments:
USER_NAME
The user name.
KEY_NAME
The unique name to be assigned to the key you wish to delete.
list-client-keys
Use the list-client-keys
subcommand to list client keys.
Syntax
This subcommand has the following syntax:
chef-server-ctl list-client-keys ORG_NAME CLIENT_NAME [--verbose]
Warning
Options
This subcommand has the following options:
CLIENT_NAME
The name of the client.
ORG_NAME
The short name for the organization to which the client belongs.
--verbose
Use to show the full public key strings in command output.
list-user-keys
Use the list-user-keys
subcommand to list client keys.
Syntax
This subcommand has the following syntax:
chef-server-ctl list-user-keys USER_NAME [--verbose]
Warning
Options
This subcommand has the following options:
USER_NAME
The user name you wish to list keys for.
--verbose
Use to show the full public key strings in command output.
Example
To view a list of user keys (including public key output):
chef-server-ctl list-user-keys applejack --verbose
Returns:
2 total key(s) found for user applejack
key_name: test-key
expires_at: Infinity
public_key:
-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA4q9Dh+bwJSjhU/VI4Y8s
9WsbIPfpmBpoZoZVPL7V6JDfIaPUkdcSdZpynhRLhQwv9ScTFh65JwxC7wNhVspB
4bKZeW6vugNGwCyBIemMfxMlpKZQDOc5dnBiRMMOgXSIimeiFtL+NmMXnGBBHDaE
b+XXI8oCZRx5MTnzEs90mkaCRSIUlWxOUFzZvnv4jBrhWsd/yBM/h7YmVfmwVAjL
VST0QG4MnbCjNtbzToMj55NAGwSdKHCzvvpWYkd62ZOquY9f2UZKxYCX0bFPNVQM
EvBQGdNG39XYSEeF4LneYQKPHEZDdqe7TZdVE8ooU/syxlZgADtvkqEoc4zp1Im3
2wIDAQAB
-----END PUBLIC KEY-----
key_name: default
expires_at: Infinity
public_key:
-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA4q9Dh+bwJSjhU/VI4Y8s
9WsbIPfpmBpoZoZVPL7V6JDfIaPUkdcSdZpynhRLhQwv9ScTFh65JwxC7wNhVspB
4bKZeW6vugNGwCyBIemMfxMlpKZQDOc5dnBiRMMOgXSIimeiFtL+NmMXnGBBHDaE
b+XXI8oCZRx5MTnzEs90mkaCRSIUlWxOUFzZvnv4jBrhWsd/yBM/h7YmVfmwVAjL
VST0QG4MnbCjNtbzToMj55NAGwSdKHCzvvpWYkd62ZOquY9f2UZKxYCX0bFPNVQM
EvBQGdNG39XYSEeF4LneYQKPHEZDdqe7TZdVE8ooU/syxlZgADtvkqEoc4zp1Im3
2wIDAQAB
-----END PUBLIC KEY-----
Maintenance Mode
Starting with Chef Infra Server 14.6.32, you can now place your Chef Infra Server into maintenance mode to block requests from Chef Infra Clients or tools like knife. Maintenance mode also allows you to specify allowed IP addresses for testing your Infra Server without allowing access to all clients.
Syntax
This subcommand has the following syntax:
- Turn on maintenance mode:
chef-server-ctl maintenance on
- Turn off maintenance mode:
chef-server-ctl maintenance off
- Add an allowed IP address:
chef-server-ctl maintenance -a IP_ADDRESS
- Remove an allowed IP address:
chef-server-ctl maintenance -r IP_ADDRESS
- List all allowed IP address:
chef-server-ctl maintenance -l
Secrets Management
Use the following commands to manage and rotate shared secrets and
service credentials. The secrets file used for storing these is located
at /etc/opscode/private-chef-secrets.json
on your Chef Infra Server.
It should be owned and readable only by root
.
set-secret
The set-secret
subcommand allows storing shared secrets and service
credentials. Only secrets known to Chef Infra Server can be stored.
Syntax
This subcommand has the following syntax:
chef-server-ctl set-secret GROUP NAME
There are various ways to pass the secret to this command:
as a third argument:
chef-server-ctl set-secret ldap bind_password secretpassword
via an environment variable:
export LDAP.BIND_PASSWORD="secretpassword" chef-server-ctl set-secret ldap bind_password
via an interactive prompt:
chef-server-ctl set-secret ldap bind_password Enter ldap bind_password: (no terminal output) Re-enter ldap bind_password: (no terminal output)
Options
This subcommand has the following options:
--with-restart
If any services depend on the secret being changed, attempt to restart them after changing the secret. Added in Chef Infra Server 12.16.2.
remove-secret
The remove-secret
subcommand allows removing a stored shared secret
and service credential.
Syntax
This subcommand has the following syntax:
chef-server-ctl remove-secret GROUP NAME
Example
chef-server-ctl remove-secret ldap bind_password
show-secret
The show-secret
subcommand allows viewing a stored shared secret and
service credential.
Syntax
This subcommand has the following syntax:
chef-server-ctl show-secret GROUP NAME
set-db-superuser-password
The set-db-superuser-password
subcommand allows storing the database
superuser password.
Syntax
This subcommand has the following syntax:
chef-server-ctl set-db-superuser-password
Similar to set-secret
, the superuser password can also be provided via
the environment variable DB_PASSWORD
.
set-actions-password
The set-actions-password
subcommand allows storing the RabbitMQ
Actions password.
Syntax
This subcommand has the following syntax:
chef-server-ctl set-actions-password
Similar to set-secret
, the action password can also be provided via
the environment variable ACTIONS_PASSWORD
.
oc-id-show-app
The oc-id-show-app
subcommand allows for retrieving the client ID and
client secret for applications known to oc-id. Note that with
insecure_addon_compat
disabled,
this data will no longer be written to /etc/opscode/oc-id-applications/APP.json
.
Syntax
This subcommand has the following syntax:
chef-server-ctl oc-id-show-app APP
Example
chef-server-ctl oc-id-show-app supermarket
{
"name": "supermarket",
"uid": "0bad0f2eb04e935718e081fb71asdfec3681c81acb9968a8e1e32451d08b",
"secret": "17cf1141cc971a10ce307611beda7ffadstr4f1bc98d9f9ca76b9b127879",
"redirect_uri": "https://supermarket.mycompany.com/auth/chef_oauth2/callback"
}
require-credential-rotation
The require-credential-rotation
subcommand takes the Chef Infra Server
offline and requires a complete service credential rotation before the
Chef Infra Server(s) in your cluster can restart again. Run
rotate-shared-secrets
to create a new shared secret, salt, and
generate the new service credentials. Then copy the secrets file to each
Chef Infra Server and run sudo chef-server-ctl reconfigure
on each
server to complete the rotation process.
Note
Syntax
This subcommand has the following syntax:
chef-server-ctl require-credential-rotation (options)
Options
This subcommand has the following options:
-y, --yes
Bypass a prompt in the terminal and agree that you want to disable the Chef Infra Server, and require credential rotation.
rotate-all-credentials
The rotate-all-credentials
subcommand generates new credential values
for all service credentials by incrementing the credential version
number and creating a new hash value. You can choose whether to copy the
updated secrets file to each node in the cluster and reconfiguring or by
running this subcommand on all the nodes.
Syntax
This subcommand has the following syntax:
chef-server-ctl rotate-all-credentials
rotate-credentials
The rotate-credentials
subcommand generates new credential values for
all credentials for a given service by incrementing the value and
creating a new hash value. You can choose whether to copy the updated
secrets file to each node in the cluster and reconfiguring or by running
this subcommand for that specific service on all the nodes.
Syntax
This subcommand has the following syntax:
chef-server-ctl rotate-credentials SERVICE_NAME
rotate-shared-secrets
The rotate-shared-secrets
subcommand creates a new shared secret and
salt, in addition to generating new service credentials. It also resets
the credential_version
number for the services to 0. After you have
run this subcommand, a new shared secret has been created, so you must
copy the secrets file to each Chef Infra Server and run
sudo chef-server-ctl reconfigure
on them to complete the rotation
process.
Syntax
This subcommand has the following syntax:
chef-server-ctl rotate-shared-secrets
show-service-credentials
The show-service-credentials
subcommand shows all of the service
credentials for services running on the local Chef Infra Server.
Syntax
This subcommand has the following syntax:
chef-server-ctl show-service-credentials
cleanup-bifrost
The cleanup-bifrost
subcommand removes unused authorization IDs for actors and objects
from the authorization database (called bifrost).
These unused actor authorization IDs can accumulate on long-running Chef Infra Servers as a result of failed actor creation requests. For most users, the unused authorization actors do not substantially affect the performance of Chef Infra Server; however in certain situations it can be helpful to clean them up.
The unused object authorization IDs can accumulate while cookbooks are uploading. During the cookbook upload, Infra Server creates a sandbox atomic transaction to verify that partial cookbook content is not uploaded to the server. This issue is fixed in Chef Infra Server 14.16.
Syntax
This subcommand has the following syntax:
chef-server-ctl cleanup-bifrost OPTIONS
Options
This subcommand has the following options:
--estimate-only
Provides an estimate of the number of unused objects that will be deleted, without deleting anything.
--wait-time SECONDS
The number of seconds to wait for in-flight requests to complete. Only decrease this value if you are running the command when the Chef Infra Server is not taking requests.
--force-cleanup
Removes internal tracking tables used during the cleanup process. Manual cleanup of these tables is only required if the cleanup command is killed unexpectedly.
--batch-size
The number of orphaned authorization actors to delete at a time.
Manage Organizations
Use theorg-create
, org-delete
, org-list
, org-show
,
org-user-add
and org-user-remove
commands to manage organizations.org-create
Theorg-create
subcommand is used to create an organization. (The
validation key for the organization is returned to STDOUT
when
creating an organization with this command.)Syntax
This subcommand has the following syntax:
chef-server-ctl org-create ORG_NAME "ORG_FULL_NAME" (options)
where:
- The 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
. - The full name must begin with a non-white space character and must
be between 1 and 1023 characters. For example:
"Chef Software, Inc."
.
Options
This subcommand has the following options:
-a USER_NAME
,--association_user USER_NAME
Associate a user with an organization and add them to the
admins
andbilling_admins
security groups.-f FILE_NAME
,--filename FILE_NAME
Write the ORGANIZATION-validator.pem to
FILE_NAME
instead of printing it toSTDOUT
.
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
chef-server-ctl org-create dev Development --association_user grantmc
org-delete
Theorg-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
Theorg-list
subcommand is used to list all of the organizations
currently present on the Chef Infra Server.Syntax
This subcommand has the following syntax:
chef-server-ctl org-list (options)
Options
This subcommand has the following options:
-a
,--all-orgs
Show all organizations.
-w
,--with-uri
Show the corresponding URIs.
org-show
Theorg-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
Theorg-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
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
Theorg-user-remove
subcommand is used to remove a user from an
organization.Warning
A user who belongs to the admins
group must be removed from the group
before they may be removed from an organization. To remove a user from
the admins
group, run the following:
EDITOR=vi knife edit /groups/admins.json
make the required changes, and then save the file.
Syntax
This subcommand has the following syntax:
chef-server-ctl org-user-remove ORG_NAME USER_NAME (options)
Options
This subcommand has the following options:
--force
Force the removal of a user from the organization’s
admins
andbilling-admins
groups.
Examples
chef-server-ctl org-user-remove prod john_smith
chef-server-ctl org-user-remove prod testmaster
chef-server-ctl org-user-remove grantmc --force
password
The password
subcommand is used to change a user’s password. When
Active Directory or LDAP is enabled, this command enables (or disables)
the system recovery password for that user. For example:
This subcommand has the following syntax:
chef-server-ctl password USERNAME
This subcommand has the following options:
--disable
Use this option to disable a user’s system recovery password.
Examples
For example, to change a user’s password, enter:
chef-server-ctl password adamjacobs
and then enter the password and confirm it:
Enter the new password: ******
Enter the new password again: ******
to return:
Password for adamjacobs successfully set.
To disable a system recovery password:
chef-server-ctl password adamjacobs --disable
to return:
Password for adamjacobs successfully disabled for System Recovery.
psql
The psql
subcommand is used to log into the PostgreSQL database
associated with the named service. This subcommand:
- Uses
psql
(the interactive terminal for PostgreSQL) - Has read-only access by default
- Is the recommended way to interact with any PostgreSQL database that is part of the Chef Infra Server
- Automatically handles authentication
Syntax
This subcommand has the following syntax:
chef-server-ctl psql SERVICE_NAME (options)
Options
This subcommand has the following options:
--write
Use to enable write access to the PostgreSQL database.
reconfigure
The reconfigure
subcommand is used when changes are made to the
chef-server.rb file to reconfigure the server. When changes are made to
the chef-server.rb file, they will not be applied to the Chef Infra
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
reindex
The reindex
subcommand is used to reload Chef Infra Server data from
PostgreSQL to Elasticsearch.
This subcommand has the following syntax:
chef-server-ctl reindex
Note
nginx['enable_non_ssl'] = false
and fips = true
require export CSC_LB_URL=https://127.0.0.1
to run the command chef-server-ctl reindex <options>
Options
This subcommand has the following options:
-a
,--all-orgs
Use to reindex all organizations on the Chef Infra Server. This option will override any organization specified as part of the command, i.e.
chef-server-ctl reindex ORG_NAME -a
will reindex all organizations and not just the specified organization.-d
,--disable-api
Use to disable the Chef Infra Server API to prevent writes during reindexing.
-t
,--with-timing
Use to print timing information for the reindex processes.
-w
,--wait
Use to wait for the reindexing queue to clear before exiting. This option only works when run on a standalone Chef Infra Server or on a primary backend Chef server within a legacy tier.
Note
If knife search
does not return the expected results and data is present in the Chef Infra Server after reindex, then verify the search index configuration with the command:
curl -XGET http://127.0.0.1:9200/_all/_settings`
Set the read_only_allow_delete
to false. Use this command to reset the search index configuration :
curl -XPUT -H "Content-Type: application/json" http://127.0.0.1:9200/_all/_settings -d '{"index.blocks.read_only_allow_delete": null}'
Server Admins
Theserver-admins
group is a global group that grants its members
permission to create, read, update, and delete user accounts, with the
exception of superuser accounts. The server-admins
group is useful for
users who are responsible for day-to-day administration of the Chef
Infra Server, especially user management using the knife user
subcommand. Before members can be added to the server-admins
group,
they must already have a user account on the Chef Infra Server.Scenario
The following user accounts exist on the Chef Infra Server: pivotal
(a
superuser account), alice
, bob
, carol
, and dan
. Run the
following command to view a list of users on the Chef Infra Server:
chef-server-ctl user-list
and it returns the same list of users:
pivotal
alice
bob
carol
dan
Alice is a member of the IT team whose responsibilities include day-to-day administration of the Chef Infra Server, in particular managing the user accounts on the Chef Infra Server that are used by the rest of the organization. From a workstation, Alice runs the following command:
knife user list -c ~/.chef/alice.rb
and it returns the following error:
ERROR: You authenticated successfully to <chef_server_url> as alice
but you are not authorized for this action
Response: Missing read permission
Alice is not a superuser and does not have permissions on other users
because user accounts are global to organizations in the Chef Infra
Server. Let’s add Alice to the server-admins
group:
chef-server-ctl grant-server-admin-permissions alice
and it returns the following response:
User alice was added to server-admins.
Alice can now create, read, update, and delete user accounts on the Chef Infra Server, even for organizations to which Alice is not a member. From a workstation, Alice re-runs the following command:
knife user list -c ~/.chef/alice.rb
which now returns:
pivotal
alice
bob
carol
dan
Alice is now a server administrator and can use the following knife subcommands to manage users on the Chef Infra Server:
knife user-create
knife user-delete
knife user-edit
knife user-list
knife user-show
For example, Alice runs the following command:
knife user edit carol -c ~/.chef/alice.rb
and the $EDITOR opens in which Alice makes changes, and then saves them.
Superuser Accounts
Superuser accounts may not be managed by users who belong to the
server-admins
group. For example, Alice attempts to delete the
pivotal
superuser account:
knife user delete pivotal -c ~/.chef/alice.rb
and the following error is returned:
ERROR: You authenticated successfully to <chef_server_url> as user1
but you are not authorized for this action
Response: Missing read permission
Alice’s action is unauthorized even with membership in the
server-admins
group.
Manage server-admins Group
Membership of the server-admins
group is managed with a set of
chef-server-ctl
subcommands:
chef-server-ctl grant-server-admin-permissions
chef-server-ctl list-server-admins
chef-server-ctl remove-server-admin-permissions
Add Members
The grant-server-admin-permissions
subcommand is used to add a user to
the server-admins
group. Run the command once for each user added.
This subcommand has the following syntax:
chef-server-ctl grant-server-admin-permissions USER_NAME
where USER_NAME
is the user to add to the list of server
administrators.
For example:
chef-server-ctl grant-server-admin-permissions bob
returns:
User bob was added to server-admins. This user can now list,
read, and create users (even for orgs they are not members of)
for this Chef Infra Server.
Remove Members
The remove-server-admin-permissions
subcommand is used to remove a
user from the server-admins
group. Run the command once for each user
removed.
This subcommand has the following syntax:
chef-server-ctl remove-server-admin-permissions USER_NAME
where USER_NAME
is the user to remove from the list of server
administrators.
For example:
chef-server-ctl remove-server-admin-permissions bob
returns:
User bob was removed from server-admins. This user can no longer
list, read, and create users for this Chef Infra Server except for where
they have default permissions (such as within an org).
List Membership
The list-server-admins
subcommand is used to return a list of users
who are members of the server-admins
group.
This subcommand has the following syntax:
chef-server-ctl list-server-admins
and will return a list of users similar to:
pivotal
alice
bob
carol
dan
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 Infra 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
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 Infra Server.
Syntax
This subcommand has the following syntax:
chef-server-ctl upgrade (options)
Options
This subcommand has the following options:
-d DIRECTORY
,--chef11-data-dir DIRECTORY
The directory in which Chef Infra Server 11 data is located. Default value: a temporary directory.
-e DIRECTORY
,--chef12-data-dir DIRECTORY
The directory in which Chef Infra Server 12 data is located. Default value: a temporary directory.
-f FULL_NAME
,--full-org-name FULL_NAME
The full name of the Chef Infra Server organization. The full 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, theupgrade
command will prompt for it.-h
,--help
Use to show help for the
chef-server-ctl upgrade
subcommand.-k KEY_PATH
,--key KEY_PATH
The Chef Infra Server 11
admin.pem
key for the API client. This is the key used to download Chef Infra Server 11 data. Default value:/etc/chef-server/admin.pem
.-o ORG_NAME
,--org-name ORG_NAME
The name of the Chef Infra Server organization. The 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, theupgrade
command will prompt for it.-s URL
,--chef11-server-url URL
The URL for the Chef Infra 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
Create a client as an admin client. This is required for any user to access Chef as an administrator.
-x URL
,--chef12-server-url URL
The URL for the Chef Infra Server, version 12. Default value:
https://localhost
.-y
,--yes
Use to skip confirmation prompts during the upgrade process.
Rebuild Migration Level File
The rebuild-migration-state subcommand attempts to recreate the migration-level file found at /var/opt/opscode/upgrades/migration-level
by inferring the current state of the database and system.
Syntax
This subcommand has the following syntax:
chef-server-ctl rebuild-migration-state
User Management
Use theuser-create
, user-delete
, user-edit
, user-list
and
user-show
subcommands to manage users.user-create
Theuser-create
subcommand is used to create a user. (The validation
key for the organization may be returned to STDOUT
when creating a
user with this command.)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
Write the USER.pem to a file instead of
STDOUT
.
Examples
chef-server-ctl user-create john_smith John Smith john_smith@example.com p@s5w0rD!
chef-server-ctl user-create jane_doe Jane Doe jane_doe@example.com p@s5w0rD! -f /tmp/jane_doe.key
chef-server-ctl user-create waldendude Henry David Thoreau waldendude@example.com excursions
user-delete
Theuser-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
Options
This subcommand has the following options:
-R
,--remove-from-admin-groups
Removes a user who is in one or more ‘admin’ groups unless that user is the only member of the ‘admin’ group(s).
user-edit
Theuser-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
Theuser-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
Show the corresponding URIs.
user-show
Theuser-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
Show all organizations.
Service Subcommands
This command has a built in process supervisor that ensures all of the required services are in the appropriate state at any given time. The supervisor starts two processes for each service and provides the following subcommands for managing services:hup
, int
, kill
, once
,
restart
, service-list
, start
, status
, stop
, tail
, and
term
.Warning
hup
, int
, kill
, once
,
restart
, start
, stop
, tail
, and term
.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 SERVICE_NAME
where SERVICE_NAME
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 SERVICE_NAME
where SERVICE_NAME
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 SERVICE_NAME
where SERVICE_NAME
represents the name of any service that is listed
after running the service-list
subcommand.
once
The supervisor for the Chef Infra 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 SERVICE_NAME
where SERVICE_NAME
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 Infra Server or to restart an individual service by specifying the
name of that service in the command.
Warning
This subcommand has the following syntax:
chef-server-ctl restart SERVICE_NAME
where SERVICE_NAME
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 Infra 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 SERVICE_NAME
where SERVICE_NAME
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 Infra 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 Infra 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 SERVICE_NAME
where SERVICE_NAME
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:
ordown:
)service_name:
is the name of the service for which status is returned(pid 12345)
is the process identifier12345s
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
Log Files
A typical status line for a service that is running any of the Chef Infra 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 eitherrun
ordown
. If a service is in adown
state, it should be stoppedname_of_service
is the service name, for example:opscode-erchef
(pid 1486) 7819s;
is the process identifier followed by the amount of time (in seconds) the service has been runningrun: 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-erchef: 3s, normally up; run: log: (pid 1485) 8526s
where
down
indicates that the service is in a down state3s, 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
Infra 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 SERVICE_NAME
where SERVICE_NAME
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: down: 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-solr4: 389s, normally up
ok: down: postgresql: 388s, normally up
ok: down: redis_lb: 387s, normally up
tail
The tail
subcommand is used to follow all of the Chef Infra 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 SERVICE_NAME
where SERVICE_NAME
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 SERVICE_NAME
where SERVICE_NAME
represents the name of any service that is listed
after running the service-list
subcommand.