Skip to content

Commit 0a6d2e4

Browse files
committed
Use new subcommands in README.
Signed-off-by: Felix Fontein <[email protected]>
1 parent d8053b9 commit 0a6d2e4

File tree

1 file changed

+34
-33
lines changed

1 file changed

+34
-33
lines changed

README.rst

Lines changed: 34 additions & 33 deletions
Original file line numberDiff line numberDiff line change
@@ -96,12 +96,12 @@ separated, in the **SOPS_PGP_FP** env variable.
9696
9797
Note: you can use both PGP and KMS simultaneously.
9898

99-
Then simply call ``sops`` with a file path as argument. It will handle the
99+
Then simply call ``sops edit`` with a file path as argument. It will handle the
100100
encryption/decryption transparently and open the cleartext file in an editor
101101

102102
.. code:: sh
103103
104-
$ sops mynewtestfile.yaml
104+
$ sops edit mynewtestfile.yaml
105105
mynewtestfile.yaml doesn't exist, creating it.
106106
please wait while an encryption key is being generated and stored in a secure fashion
107107
file written to mynewtestfile.yaml
@@ -164,7 +164,7 @@ Given that, the only command a SOPS user needs is:
164164

165165
.. code:: sh
166166
167-
$ sops <file>
167+
$ sops edit <file>
168168
169169
`<file>` will be opened, decrypted, passed to a text editor (vim by default),
170170
encrypted if modified, and saved back to its original location. All of these
@@ -179,7 +179,7 @@ the example files and pgp key provided with the repository::
179179
$ git clone https://github.com/getsops/sops.git
180180
$ cd sops
181181
$ gpg --import pgp/sops_functional_tests_key.asc
182-
$ sops example.yaml
182+
$ sops edit example.yaml
183183

184184
This last step will decrypt ``example.yaml`` using the test private key.
185185

@@ -431,35 +431,33 @@ separated list.
431431
SOPS will prompt you with the changes to be made. This interactivity can be
432432
disabled by supplying the ``-y`` flag.
433433
434-
Command Line
435-
************
434+
``rotate`` command
435+
******************
436436
437-
Command line flag ``--add-kms``, ``--add-pgp``, ``--add-gcp-kms``, ``--add-azure-kv``,
438-
``--rm-kms``, ``--rm-pgp``, ``--rm-gcp-kms`` and ``--rm-azure-kv`` can be used to add
439-
and remove keys from a file.
440-
These flags use the comma separated syntax as the ``--kms``, ``--pgp``, ``--gcp-kms``
441-
and ``--azure-kv`` arguments when creating new files.
437+
The ``rotate`` command generates a new data encryption key and reencrypt all values
438+
with the new key. At te same time, the command line flag ``--add-kms``, ``--add-pgp``,
439+
``--add-gcp-kms``, ``--add-azure-kv``, ``--rm-kms``, ``--rm-pgp``, ``--rm-gcp-kms``
440+
and ``--rm-azure-kv`` can be used to add and remove keys from a file. These flags use
441+
the comma separated syntax as the ``--kms``, ``--pgp``, ``--gcp-kms`` and ``--azure-kv``
442+
arguments when creating new files.
442443
443-
Note that ``-r`` or ``--rotate`` is mandatory in this mode. Not specifying
444-
rotate will ignore the ``--add-*`` options. Use ``updatekeys`` if you want to
445-
add a key without rotating the data key.
444+
Use ``updatekeys`` if you want to add a key without rotating the data key.
446445
447446
.. code:: sh
448447
449448
# add a new pgp key to the file and rotate the data key
450-
$ sops -r -i --add-pgp 85D77543B3D624B63CEA9E6DBC17301B491B3F21 example.yaml
449+
$ sops rotate -i --add-pgp 85D77543B3D624B63CEA9E6DBC17301B491B3F21 example.yaml
451450
452451
# remove a pgp key from the file and rotate the data key
453-
$ sops -r -i --rm-pgp 85D77543B3D624B63CEA9E6DBC17301B491B3F21 example.yaml
452+
$ sops rotate -i --rm-pgp 85D77543B3D624B63CEA9E6DBC17301B491B3F21 example.yaml
454453
455454
456455
Direct Editing
457456
**************
458457
459-
Alternatively, invoking ``sops`` with the flag **-s** will display the master keys
458+
Alternatively, invoking ``sops edit`` with the flag **-s** will display the master keys
460459
while editing. This method can be used to add or remove ``kms`` or ``pgp`` keys under the
461-
``sops`` section. Invoking ``sops`` with the **-i** flag will perform an in-place edit
462-
instead of redirecting output to ``stdout``.
460+
``sops`` section.
463461
464462
For example, to add a KMS master key to a file, add the following entry while
465463
editing:
@@ -571,7 +569,7 @@ When creating a new file, you can specify the encryption context in the
571569
572570
.. code:: sh
573571
574-
$ sops --encryption-context Environment:production,Role:web-server test.dev.yaml
572+
$ sops edit --encryption-context Environment:production,Role:web-server test.dev.yaml
575573
576574
The format of the Encrypt Context string is ``<EncryptionContext Key>:<EncryptionContext Value>,<EncryptionContext Key>:<EncryptionContext Value>,...``
577575
@@ -602,13 +600,16 @@ Key Rotation
602600
~~~~~~~~~~~~
603601
604602
It is recommended to renew the data key on a regular basis. ``sops`` supports key
605-
rotation via the ``-r`` flag. Invoking it on an existing file causes ``sops`` to
606-
reencrypt the file with a new data key, which is then encrypted with the various
603+
rotation via the ``rotate`` command. Invoking it on an existing file causes ``sops``
604+
to reencrypt the file with a new data key, which is then encrypted with the various
607605
KMS and PGP master keys defined in the file.
608606
607+
Add the ``-i`` option to write the rotated file back, instead of printing it to
608+
stdout.
609+
609610
.. code:: sh
610611
611-
$ sops -r example.yaml
612+
$ sops rotate example.yaml
612613
613614
Using .sops.yaml conf to select KMS, PGP and age for new files
614615
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -692,7 +693,7 @@ Creating a new file with the right keys is now as simple as
692693
693694
.. code:: sh
694695
695-
$ sops <newfile>.prod.yaml
696+
$ sops edit <newfile>.prod.yaml
696697
697698
Note that the configuration file is ignored when KMS or PGP parameters are
698699
passed on the SOPS command line or in environment variables.
@@ -798,7 +799,7 @@ For example:
798799
799800
.. code:: sh
800801
801-
$ sops --shamir-secret-sharing-threshold 2 example.json
802+
$ sops edit --shamir-secret-sharing-threshold 2 example.json
802803
803804
Alternatively, you can configure the Shamir threshold for each creation rule in the ``.sops.yaml`` config
804805
with ``shamir_threshold``:
@@ -831,7 +832,7 @@ with ``shamir_threshold``:
831832
- pgp:
832833
- fingerprint5
833834
834-
And then run ``sops example.json``.
835+
And then run ``sops edit example.json``.
835836
836837
The threshold (``shamir_threshold``) is set to 2, so this configuration will require
837838
master keys from two of the three different key groups in order to decrypt the file.
@@ -1263,7 +1264,7 @@ The command below creates a new file with a data key encrypted by KMS and PGP.
12631264
12641265
.. code:: sh
12651266
1266-
$ sops --kms "arn:aws:kms:us-west-2:927034868273:key/fe86dd69-4132-404c-ab86-4269956b4500" --pgp C9CAB0AF1165060DB58D6D6B2653B624D620786D /path/to/new/file.yaml
1267+
$ sops edit --kms "arn:aws:kms:us-west-2:927034868273:key/fe86dd69-4132-404c-ab86-4269956b4500" --pgp C9CAB0AF1165060DB58D6D6B2653B624D620786D /path/to/new/file.yaml
12671268
12681269
Encrypting an existing file
12691270
~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -1363,26 +1364,26 @@ Set a sub-part in a document tree
13631364
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
13641365
13651366
SOPS can set a specific part of a YAML or JSON document, by providing
1366-
the path and value in the ``--set`` command line flag. This is useful to
1367-
set specific values, like keys, without needing an editor.
1367+
the path and value in the ``set`` command. This is useful to set specific
1368+
values, like keys, without needing an editor.
13681369
13691370
.. code:: sh
13701371
1371-
$ sops --set '["app2"]["key"] "app2keystringvalue"' ~/git/svc/sops/example.yaml
1372+
$ sops set ~/git/svc/sops/example.yaml '["app2"]["key"]' '"app2keystringvalue"'
13721373
13731374
The tree path syntax uses regular python dictionary syntax, without the
13741375
variable name. Set to keys by naming them, and array elements by
13751376
numbering them.
13761377
13771378
.. code:: sh
13781379
1379-
$ sops --set '["an_array"][1] "secretuser2"' ~/git/svc/sops/example.yaml
1380+
$ sops set ~/git/svc/sops/example.yaml '["an_array"][1]' '"secretuser2"'
13801381
13811382
The value must be formatted as json.
13821383
13831384
.. code:: sh
13841385
1385-
$ sops --set '["an_array"][1] {"uid1":null,"uid2":1000,"uid3":["bob"]}' ~/git/svc/sops/example.yaml
1386+
$ sops set ~/git/svc/sops/example.yaml '["an_array"][1]' '{"uid1":null,"uid2":1000,"uid3":["bob"]}'
13861387
13871388
Showing diffs in cleartext in git
13881389
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -1651,7 +1652,7 @@ when creating a new file:
16511652
16521653
.. code:: sh
16531654
1654-
$ sops --pgp "E60892BB9BD89A69F759A1A0A3D652173B763E8F,84050F1D61AF7C230A12217687DF65059EF093D3,85D77543B3D624B63CEA9E6DBC17301B491B3F21" mynewfile.yaml
1655+
$ sops edit --pgp "E60892BB9BD89A69F759A1A0A3D652173B763E8F,84050F1D61AF7C230A12217687DF65059EF093D3,85D77543B3D624B63CEA9E6DBC17301B491B3F21" mynewfile.yaml
16551656
16561657
Threat Model
16571658
------------

0 commit comments

Comments
 (0)