Remove link to incomplete and severely outdated
client_setup_and_repository_example.md in client section of
TUTORIAL.md.
Instead we should link (or move the entire client tutorial part) to
tuf/client/README.md, which is more comprehensive and less outdated
than above document (see #808).
Signed-off-by: Lukas Puehringer <lukas.puehringer@nyu.edu>
In tutorial code snippet fix a call to repository.mark_dirty that
passes a non-existing bin role name raising:
"tuf.exceptions.UnknownRoleError: Role name does not exist: 90-7"
Signed-off-by: Lukas Puehringer <lukas.puehringer@nyu.edu>
TUF does not reliably mark roles as dirty whose metadata needs
to be re-generated.
Only roles that have changed are marked as dirty, but sometimes
roles metadata needs to be updated, although the role wasn't
changed directly (see #958).
Furthermore, the tutorial assumes at one point that the reader
leaves and re-enter the interpreter session, being forced to reload the
signing keys, roles that later need to be re-written, are marked as
dirty. If the reader does not leave the interpreter, the roles are
not marked as dirty (see #964).
To not confuse the reader with flawed state-keeping, and to never
write an inconsistent repository to disk, the tutorial lets the
reader explicitly mark all roles that need to be re-written as
"dirty".
This can be changed once above issues are fixed.
Signed-off-by: Lukas Puehringer <lukas.puehringer@nyu.edu>
Explain and show output of delegate_hashed_bins() function call in
tutorial snippet.
Also update the subsequent comment for better continuity.
Signed-off-by: Lukas Puehringer <lukas.puehringer@nyu.edu>
- Ask the reader to ignore a misleading warning about the location of
a delegation path pattern.
The comment may be removed when fixing the warning in
theupdateframework/tuf#963.
- Comment out text that has become obsolete when commenting out
the "Revoke Delegated Role" section (in an earlier commit).
Signed-off-by: Lukas Puehringer <lukas.puehringer@nyu.edu>
The text above the snippet explains the basic idea of "consistent
snapshots" and how to generate them with `write` and `writeall`.
The commands in the snippet just leave the repo in an inconsistent
state (see comment).
Signed-off-by: Lukas Puehringer <lukas.puehringer@nyu.edu>
- Fix expected output
- Update comments
- Add a few additional calls, to help the reader understand the
repo state
- Also see theupdateframework/tuf#958
Signed-off-by: Lukas Puehringer <lukas.puehringer@nyu.edu>
In "Targets" section:
- Remove `repository.targets('<delegated rolename>').add_target(...)`
command, because it is not copy-pastable and delegations
have not yet been covered at that point.
- Update the "remove targets" snippet to remove the previously added
"myproject/file4.txt" instead of "file3.txt", because we will add
"myproject/file4.txt" to the delegated "unclaimed" role in the
Delegation section.
In "Delegation" section:
- Change "unclaimed" delegation pattern from 'foo*.tgz', for which
no file exists in the tutorial, to 'myproject/*.txt'.
- Add "myproject/file4.txt" to the delegated unclaimed targets role
- Remove the command that updates the version of the "unclaimed"
role, because this should not be done manually, and the add_target
call shows just as well how to access delegated roles.
- Comment out the revoke delgated role section, leaving a TODO note
for required updates (should be ticketized).
In "Delegate to Hashed Bins":
- Add call to remove target "myproject/file4.txt" from "unclaimed",
because it is further delgated to hashed bins
- Add dirty_roles() call to show all the newly created bins
- Add mark_dirty() and writeall() calls to create a consistent
state of the repo
Signed-off-by: Lukas Puehringer <lukas.puehringer@nyu.edu>
The section does not fit in the continuity of the tutorial and
misses commands to make it fully copy-pastable.
This commit marks the section as "Excursion" and updates the
snippets to make the commands fully copy-pastable, using files
created in prior tutorial sections.
Signed-off-by: Lukas Puehringer <lukas.puehringer@nyu.edu>
- Correctly show that repo.get_filepaths_in_directory() returns
absolute and not relative paths
- Pass absolute path to repo.targets.add_target() to fix exception
- Also see theupdateframework/tuf#957
Signed-off-by: Lukas Puehringer <lukas.puehringer@nyu.edu>
Reasons are:
- The prompt says 2.7.3 Sep 26 2013, which makes the tutorial look
outdated
- There is another section that explains how snippets should be
executed in a Python interactive interpreter
- The only activity in the snippet is importing tuf functions and
creating a repo, both of which is done in another snippet below.
And the here created repo is not re-used
- The tutorial is long enough
Signed-off-by: Lukas Puehringer <lukas.puehringer@nyu.edu>
Because leading '/' is no longer allowed in target filenames in
target addition or delegation.
See https://github.com/theupdateframework/tuf/issues/639
While we're at it, remove some other unnecessary '/' characters
in repository creation and loading in the tutorial and tutorial
test.
Signed-off-by: Sebastien Awwad <sebastien.awwad@gmail.com>
add_restricted_paths was renamed to add_path; however, this
function represents a problematic element of TUF that assumes
that roles are have a single delegator and delegatee, and that
one can refer to a role's expected keys without being concerned
about any delegation metadata....
So this is being removed from the tutorial. In time, add_paths
will either be removed or changed (to expect a delegator role
and a delegatee role, not just a delegatee role).
This comment does not do justice to the issue: please see TUF
GitHub Issue #660:
https://github.com/theupdateframework/tuf/issues/660
Signed-off-by: Sebastien Awwad <sebastien.awwad@gmail.com>
While it may be nice, the use of a keystore/ directory for the
temporary keys created in the tutorial complicates the code a
good bit when it's done in a portable way (tons of os.path.join()
calls), and that's not worth it. It also is a slight complication
in a tutorial that profits from being as simple as possible.
Tests will be run in multiple environments (including non-Linux
environments) and to leave so many extra subdirectory uses in the
tutorial means that the tutorial test will deviate over a large
number of lines from the TUTORIAL.md content it is intended to
test, which would be bad.
This commit adjusts both the tutorial doc and the regression test
for the tutorial.
Signed-off-by: Sebastien Awwad <sebastien.awwad@gmail.com>
- line-wraps are integrated with
190a736d297ef5d8d3c1e8761ac196666954f3a2 in #775
- sorting the value returned by `get_dirty_roles()` in
`dirty_roles()` is not necessary as `get_dirty_roles()` already
returns a sorted list per ac010337f0e154f9c183f8abe759ce26ed16731c
in #775.
Signed-off-by: Lukas Puehringer <lukas.puehringer@nyu.edu>
An attempt to make part of the tutorial less jarring, and reformatting
of the surrounding text to keep the lines <80 characters.
Signed-off-by: Joshua Lock <jlock@vmware.com>
Add note to make clear what was implicit: that once a delegated role is created,
it can be accessed (for the same purposes as you'd access the Targets role
using `repository.targets`) as: `repository.targets("<delegated rolename>")`.
Also add that specific note to the add_targets section of the tutorial.
Some users will actually attempt to execute the example listed in the overview section. Use a working example that doesn't raise an error.
Signed-off-by: Vladimir Diaz <vladimir.v.diaz@gmail.com>
* The client script is now named 'client.py' and the user is no longer required to manually copy the basic_client.py to the CWD
* A log file is not saved to the CWD, by default
* The client.py script doesn't download all target files available on the repo.
Signed-off-by: Vladimir Diaz <vladimir.v.diaz@gmail.com>
Correct links to modules and documentation.
Broken links appear to be mostly fallout from moving
documentation into the docs/ directory, as relative paths
to python source modules were broken.
