Merge pull request #10 from felixfontein/docs

Clean up a little bit, and convert commits from main repository's README

Author: sabre1041

config.yaml

@@ -1,5 +1,5 @@
 # THIS IS A TEST CONFIG ONLY!
-# FOR THE CONFIGURATION OF YOUR SITE USE hugo.yaml.
+# FOR THE CONFIGURATION OF YOUR SITE USE hugo.toml.
 #
 # As of Docsy 0.7.0, Hugo 0.110.0 or later must be used.
 #

content/en/docs/_index.md

@@ -203,6 +203,22 @@ can use the example files and pgp key provided with the repository:
 
 This last step will decrypt `example.yaml` using the test private key.
 
+## Encrypting with GnuPG subkeys
+
+If you want to encrypt with specific GnuPG subkeys, it does not suffice to provide the
+exact key ID of the subkey to SOPS, since GnuPG might use *another* subkey instead
+to encrypt the file key with. To force GnuPG to use a specific subkey, you need to
+append `!` to the key's fingerprint.
+
+``` yaml
+creation_rules:
+    - pgp: >-
+        85D77543B3D624B63CEA9E6DBC17301B491B3F21!,
+        E60892BB9BD89A69F759A1A0A3D652173B763E8F!
+```
+
+Please note that this is only passed on correctly to GnuPG since SOPS 3.9.3.
+
 ## Encrypting using age
 
 [age](https://age-encryption.org/) is a simple, modern, and secure tool
@@ -234,6 +250,28 @@ decrypt the data.
 
 Encrypting with SSH keys via age is not yet supported by SOPS.
 
+A list of age recipients can be added to the `.sops.yaml`:
+
+``` yaml
+creation_rules:
+    - age: >-
+        age1s3cqcks5genc6ru8chl0hkkd04zmxvczsvdxq99ekffe4gmvjpzsedk23c,
+        age1qe5lxzzeppw5k79vxn3872272sgy224g2nzqlzy3uljs84say3yqgvd0sw
+```
+
+It is also possible to use `updatekeys`, when adding or removing age recipients. For example:
+
+``` sh
+$ sops updatekeys secret.enc.yaml
+2022/02/09 16:32:02 Syncing keys for file /iac/solution1/secret.enc.yaml
+The following changes will be made to the file's groups:
+Group 1
+    age1s3cqcks5genc6ru8chl0hkkd04zmxvczsvdxq99ekffe4gmvjpzsedk23c
++++ age1qe5lxzzeppw5k79vxn3872272sgy224g2nzqlzy3uljs84say3yqgvd0sw
+Is this okay? (y/n):y
+2022/02/09 16:32:04 File /iac/solution1/secret.enc.yaml synced with new keys
+```
+
 ## Encrypting using GCP KMS
 
 GCP KMS uses [Application Default
@@ -689,6 +727,9 @@ stored under a specific directory, like a `git` repository, you can
 create a `.sops.yaml` configuration file at the root directory to define
 which keys are used for which filename.
 
+Note: The file needs to be named `.sops.yaml`. Other names (i.e. `.sops.yml`) won't be automatically
+discovered by sops. You'll need to pass the `--config .sops.yml` option for it to be picked up.
+
 Let\'s take an example:
 
 -   file named **something.dev.yaml** should use one set of KMS A, PGP
@@ -1514,6 +1555,24 @@ The value must be formatted as json.
 $ sops set ~/git/svc/sops/example.yaml '["an_array"][1]' '{"uid1":null,"uid2":1000,"uid3":["bob"]}'
 ```
 
+## Unset a sub-part in a document tree
+
+Symmetrically, SOPS can unset a specific part of a YAML or JSON document, by providing
+the path in the `unset` command. This is useful to unset specific values, like keys, without
+needing an editor.
+
+``` sh
+$ sops unset ~/git/svc/sops/example.yaml '["app2"]["key"]'
+```
+
+The tree path syntax uses regular python dictionary syntax, without the
+variable name. Set to keys by naming them, and array elements by
+numbering them.
+
+``` sh
+$ sops unset ~/git/svc/sops/example.yaml '["an_array"][1]'
+```
+
 ## Showing diffs in cleartext in git
 
 You most likely want to store encrypted files in a version controlled
@@ -1597,10 +1656,20 @@ will not encrypt the values under the `description` and `metadata` keys
 in a YAML file containing kubernetes secrets, while encrypting
 everything else.
 
+For YAML files, another method is to use `--encrypted-comment-regex` which will
+only encrypt comments and values which have a preceding comment matching the supplied
+regular expression.
+
+Conversely, you can opt in to only left certain keys without encrypting by using the
+`--unencrypted-comment-regex` option, which will leave the values and comments
+unencrypted when they have a preeceding comment, or a trailing comment on the same line,
+that matches the supplied regular expression.
+
 You can also specify these options in the `.sops.yaml` config file.
 
-Note: these four options `--unencrypted-suffix`, `--encrypted-suffix`,
-`--encrypted-regex` and `--unencrypted-regex` are mutually exclusive and
+Note: these six options `--unencrypted-suffix`, `--encrypted-suffix`,
+`--encrypted-regex`, `--unencrypted-regex`, `--encrypted-comment-regex`,
+and `--unencrypted-comment-regex` are mutually exclusive and
 cannot all be used in the same file.
 
 # Encryption Protocol

hugo.toml

@@ -105,7 +105,7 @@ version = "0.0"
 url_latest_version = "https://example.com"
 
 # Repository configuration (URLs for in-page links to opening issues and suggesting changes)
-github_repo = "https://github.com/getsops/sops"
+github_repo = "https://github.com/getsops/docs"
 # An optional link to a related project repo. For example, the sibling repository where your product code lives.
 github_project_repo = "https://github.com/getsops/sops"
 
@@ -117,7 +117,7 @@ github_project_repo = "https://github.com/getsops/sops"
 github_branch= "main"
 
 # Google Custom Search Engine ID. Remove or comment out to disable search.
-gcs_engine_id = "d72aa9b2712488cc3"
+# gcs_engine_id = "d72aa9b2712488cc3"
 
 # Enable Lunr.js offline search
 offlineSearch = false
@@ -149,8 +149,8 @@ sidebar_search_disable = false
 [params.ui.feedback]
 enable = true
 # The responses that the user sees after clicking "yes" (the page was helpful) or "no" (the page was not helpful).
-yes = 'Glad to hear it! Please <a href="https://github.com/USERNAME/REPOSITORY/issues/new">tell us how we can improve</a>.'
-no = 'Sorry to hear that. Please <a href="https://github.com/USERNAME/REPOSITORY/issues/new">tell us how we can improve</a>.'
+yes = 'Glad to hear it! Please <a href="https://github.com/getsops/sops/issues/new">tell us how we can improve</a>.'
+no = 'Sorry to hear that. Please <a href="https://github.com/getsops/sops/issues/new">tell us how we can improve</a>.'
 
 # Adds a reading time to the top of each doc.
 # If you want this feature, but occasionally need to remove the Reading time from a single page,
@@ -160,16 +160,16 @@ enable = false
 
 [params.links]
 # End user relevant links. These will show up on left side of footer and in the community page if you have one.
-[[params.links.user]]
-  name = "User mailing list"
-  url = "https://example.org/mail"
-  icon = "fa fa-envelope"
-  desc = "Discussion and help from your fellow users"
-[[params.links.user]]
-  name ="Twitter"
-  url = "https://example.org/twitter"
-  icon = "fab fa-twitter"
-  desc = "Follow us on Twitter to get the latest news!"
+#[[params.links.user]]
+#  name = "User mailing list"
+#  url = "https://example.org/mail"
+#  icon = "fa fa-envelope"
+#  desc = "Discussion and help from your fellow users"
+#[[params.links.user]]
+#  name ="Twitter"
+#  url = "https://example.org/twitter"
+#  icon = "fab fa-twitter"
+#  desc = "Follow us on Twitter to get the latest news!"
 [[params.links.user]]
   name = "Stack Overflow"
   url = "https://stackoverflow.com/questions/tagged/mozilla-sops"
@@ -186,11 +186,11 @@ enable = false
   url = "https://slack.cncf.io"
   icon = "fab fa-slack"
   desc = "Chat with other project developers"
-[[params.links.developer]]
-  name = "Developer mailing list"
-  url = "https://example.org/mail"
-  icon = "fa fa-envelope"
-  desc = "Discuss development issues around the project"
+#[[params.links.developer]]
+#  name = "Developer mailing list"
+#  url = "https://example.org/mail"
+#  icon = "fa fa-envelope"
+#  desc = "Discuss development issues around the project"
 
 # hugo module configuration
 

layouts/404.html

@@ -2,6 +2,5 @@
 <div class="td-content">
   <h1>Not found</h1>
   <p>Oops! This page doesn't exist. Try going back to the <a href="{{ "" | relURL }}">home page</a>.</p>
-  <p>You can learn how to make a 404 page like this in <a href="https://gohugo.io/templates/404/">Custom 404 Pages</a>.</p>
 </div>
 {{- end }}