ocket8888 commented on a change in pull request #5913:
URL: https://github.com/apache/trafficcontrol/pull/5913#discussion_r648503646
##########
File path: docs/source/admin/traffic_vault.rst
##########
@@ -79,6 +79,40 @@ Administration of the PostgreSQL database for Traffic Vault
Similar to administering the Traffic Ops database, the :ref:`admin
<database-management>` tool should be used for administering the PostgreSQL
Traffic Vault backend.
+AES Re-Encryption Tool:
Review comment:
Association of a heading with its content is done by virtue of it being
a heading - you don't need the <kbd>:</kbd>
##########
File path: docs/source/admin/traffic_vault.rst
##########
@@ -79,6 +79,40 @@ Administration of the PostgreSQL database for Traffic Vault
Similar to administering the Traffic Ops database, the :ref:`admin
<database-management>` tool should be used for administering the PostgreSQL
Traffic Vault backend.
+AES Re-Encryption Tool:
+-----------------------
+
+.. program:: reencrypt
+
+app/db/reencrypt/reencrypt
+=====================================================================
Review comment:
This heading level (`====`) places this heading above the previous
section "AES Re-Encryption Tool:". In HTML terms, this is something like
```html
<section>
<h1>Traffic Vault Administration</h1>
<!-- some content... -->
<section>
<h2>PostgreSQL</h2>
<!-- some content... -->
<section>
<h3>AES Re-Encryption Tool:</h3>
</section>
</section>
<section>
<h2>app/db/reencrypt/reencrypt</h2>
<!-- some content... -->
</section>
<!-- some content -->
</section>
```
when I think what you actually want is something more like
```html
<section>
<h1>Traffic Vault Administration</h1>
<!-- some content... -->
<section>
<h2>PostgreSQL</h2>
<!-- some content... -->
<section>
<h3>AES Re-Encryption Tool:</h3>
<section>
<h4>app/db/reencrypt/reencrypt</h4>
<!-- some content... -->
</section>
</section>
<!-- some content... -->
</section>
<!-- some content -->
</section>
```
although, the "AES Re-Encryption Tool:" section contains no content besides
the content contained in its sub-section in that case, so really you don't need
it, so this could just simply be structured:
```html
<section>
<h1>Traffic Vault Administration</h1>
<!-- some content... -->
<section>
<h2>PostgreSQL</h2>
<!-- some content... -->
<section>
<h3>app/db/reencrypt/reencrypt</h3>
<!-- some content... -->
</section>
<!-- some content... -->
</section>
<!-- some content -->
</section>
```
##########
File path: docs/source/admin/traffic_vault.rst
##########
@@ -79,6 +79,40 @@ Administration of the PostgreSQL database for Traffic Vault
Similar to administering the Traffic Ops database, the :ref:`admin
<database-management>` tool should be used for administering the PostgreSQL
Traffic Vault backend.
+AES Re-Encryption Tool:
+-----------------------
+
+.. program:: reencrypt
+
+app/db/reencrypt/reencrypt
+=====================================================================
+The :program:`app/db/reencrypt/reencrypt` binary is for use to re-encrypt all
keys in the Postgres Traffic Vault.
Review comment:
> ... binary is for use to re-encrypt ...
grammar
##########
File path: docs/source/admin/traffic_vault.rst
##########
@@ -79,6 +79,40 @@ Administration of the PostgreSQL database for Traffic Vault
Similar to administering the Traffic Ops database, the :ref:`admin
<database-management>` tool should be used for administering the PostgreSQL
Traffic Vault backend.
+AES Re-Encryption Tool:
+-----------------------
+
+.. program:: reencrypt
+
+app/db/reencrypt/reencrypt
+=====================================================================
+The :program:`app/db/reencrypt/reencrypt` binary is for use to re-encrypt all
keys in the Postgres Traffic Vault.
+
+.. note:: For proper resolution of configuration files, it's recommended that
this binary be run from the ``app/db/reencrypt`` directory
Review comment:
Missing punctuation
##########
File path: docs/source/admin/traffic_vault.rst
##########
@@ -79,6 +79,40 @@ Administration of the PostgreSQL database for Traffic Vault
Similar to administering the Traffic Ops database, the :ref:`admin
<database-management>` tool should be used for administering the PostgreSQL
Traffic Vault backend.
+AES Re-Encryption Tool:
+-----------------------
+
+.. program:: reencrypt
+
+app/db/reencrypt/reencrypt
+=====================================================================
Review comment:
I don't think it's actually a problem for rendering, but this underline
is much, much longer than the title it underlines
##########
File path: docs/source/admin/traffic_vault.rst
##########
@@ -79,6 +79,40 @@ Administration of the PostgreSQL database for Traffic Vault
Similar to administering the Traffic Ops database, the :ref:`admin
<database-management>` tool should be used for administering the PostgreSQL
Traffic Vault backend.
+AES Re-Encryption Tool:
+-----------------------
+
+.. program:: reencrypt
+
+app/db/reencrypt/reencrypt
+=====================================================================
+The :program:`app/db/reencrypt/reencrypt` binary is for use to re-encrypt all
keys in the Postgres Traffic Vault.
+
+.. note:: For proper resolution of configuration files, it's recommended that
this binary be run from the ``app/db/reencrypt`` directory
+
+Usage
+-----
+``./reencrypt [options]``
+
+Options and Arguments
+---------------------
+.. option:: --new-key
+
+ The file path for the new base64-encoded AES key.
+
+.. option:: --previous-key
+
+ The file path for the previous base64-encoded AES key.
+
+.. option:: --cfg
+
+ The path for the configuration file. Default is ``./reencrypt.conf``.
Review comment:
Options that take option-arguments should indicate so in their `..
option::` directive, e.g. `.. option:: --new-key NEW_KEY` - as opposed to
options without option-arguments like `.. option:: -h, --help` (which, by the
way, is an option I'd encourage all utilities to implement).
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
[email protected]
