X-Git-Url: http://git.onelab.eu/?a=blobdiff_plain;f=docs%2Fpythondoc-registry.html;fp=docs%2Fpythondoc-registry.html;h=ba1891e4463b86896ab93e453f29034bf7e5dfe6;hb=7723a3ad29690212b271cb53f88b78e2469e671d;hp=0000000000000000000000000000000000000000;hpb=fe4139adc9c8902084ecedc9f05a739faba11b7a;p=sfa.git diff --git a/docs/pythondoc-registry.html b/docs/pythondoc-registry.html new file mode 100644 index 00000000..ba1891e4 --- /dev/null +++ b/docs/pythondoc-registry.html @@ -0,0 +1,433 @@ + + + + +The registry Module + + +

The registry Module

+

Geni Registry Wrapper + +This wrapper implements the Geni Registry. + +There are several items that need to be done before starting the registry. + +1) Update util/config.py to match the parameters of your PLC installation. + +2) Import the existing planetlab database, creating the +appropriate geni records. This is done by running the "import.py" tool. + +3) Create a "trusted_roots" directory and place the certificate of the root +authority in that directory. Given the defaults in import.py, this certificate +would be named "planetlab.gid". For example, + + mkdir trusted_roots; cp authorities/planetlab.gid trusted_roots/

+
+
geni_fields_to_pl_fields(type, hrn, geni_fields, pl_fields) [#]
+
+

Convert geni fields to PLC fields for use when registering up updating +registry record in the PLC database

+
+
type
+
+type of record (user, slice, ...)
+
hrn
+
+human readable name
+
geni_fields
+
+dictionary of geni fields
+
pl_fields
+
+dictionary of PLC fields (output)
+

+
+
Registry(ip, port, key_file, cert_file) (class) [#]
+
+

Registry is a GeniServer that serves registry requests.

+

For more information about this class, see The Registry Class.

+
+
+

The Registry Class

+
+
Registry(ip, port, key_file, cert_file) (class) [#]
+
+

Registry is a GeniServer that serves registry requests. It also serves +component and slice operations that are implemented on the registry +due to SFA engineering decisions

+
+
connect_local_shell() [#]
+
+

Connect to a local shell via local API functions

+
+
connect_remote_shell() [#]
+
+

Connect to a remote shell via XMLRPC

+
+
create_gid(cred, name, uuid, pubkey_str) [#]
+
+

GENI_API: Create_gid + +Create a new GID. For MAs and SAs that are physically located on the +registry, this allows a owner/operator/PI to create a new GID and have it +signed by his respective authority.

+
+
cred
+
+credential of caller
+
name
+
+hrn for new GID
+
uuid
+
+unique identifier for new GID
+
pkey_string
+
+public-key string (TODO: why is this a string and not a keypair object?)
+
Returns:
+
+the string representation of a GID object
+

+
+
determine_rights(type, name) [#]
+
+

Determine tje rights that an object should have. The rights are entirely +dependent on the type of the object. For example, users automatically +get "refresh", "resolve", and "info".

+
+
type
+
+the type of the object (user | sa | ma | slice | node)
+
name
+
+human readable name of the object (not used at this time)
+
Returns:
+
+RightList object containing rights
+

+
+
fill_record_geni_info(record) [#]
+
+

Fill in the geni-specific fields of the record. + +Note: It is assumed the fill_record_pl_info() has already been performed +on the record.

+
+
fill_record_info(record) [#]
+
+

Given a Geni record, fill in the PLC-specific and Geni-specific fields +in the record.

+
+
fill_record_pl_info(record) [#]
+
+

Fill in the planetlab-specific fields of a Geni record. This involves +calling the appropriate PLC methods to retrieve the database record for +the object. + +PLC data is filled into the pl_info field of the record.

+
+
record
+
+record to fill in fields (in/out param)
+

+
+
get_auth_info(auth_hrn) [#]
+
+

Given an authority name, return the information for that authority. This +is basically a stub that calls the hierarchy module.

+
+
auth_hrn
+
+human readable name of authority
+

+
+
get_auth_table(auth_name) [#]
+
+

Given an authority name, return the database table for that authority. If +the database table does not exist, then one will be automatically +created.

+
+
auth_name
+
+human readable name of authority
+

+
+
get_credential(cred, type, name) [#]
+
+

GENI API: Get_credential + +Retrieve a credential for an object. + +If cred==None, then the behavior reverts to get_self_credential()

+
+
cred
+
+credential object specifying rights of the caller
+
type
+
+type of object (user | slice | sa | ma | node)
+
name
+
+human readable name of object
+
Returns:
+
+the string representation of a credental object
+

+
+
get_gid(name) [#]
+
+

GENI API: get_gid + +Retrieve the GID for an object. This function looks up a record in the +registry and returns the GID of the record if it exists. +TODO: Is this function needed? It's a shortcut for Resolve()

+
+
name
+
+hrn to look up
+
Returns:
+
+the string representation of a GID object
+

+
+
get_self_credential(type, name) [#]
+
+

GENI API: Get_self_credential + +Get_self_credential a degenerate version of get_credential used by a +client to get his initial credential when he doesn't have one. This is +the same as get_credential(..., cred=None,...). + +The registry ensures that the client is the principal that is named by +(type, name) by comparing the public key in the record's GID to the +private key used to encrypt the client-side of the HTTPS connection. Thus +it is impossible for one principal to retrieve another principal's +credential without having the appropriate private key.

+
+
type
+
+type of object (user | slice | sa | ma | node
+
name
+
+human readable name of object
+
Returns:
+
+the string representation of a credential object
+

+
+
get_ticket(cred, name, rspec) [#]
+
+

GENI API: get_ticket + +Retrieve a ticket. This operation is currently implemented on the +registry (see SFA, engineering decisions), and is not implemented on +components. + +The ticket is filled in with information from the PLC database. This +information includes resources, and attributes such as user keys and +initscripts.

+
+
cred
+
+credential string
+
name
+
+name of the slice to retrieve a ticket for
+
rspec
+
+resource specification dictionary
+
Returns:
+
+the string representation of a ticket object
+

+
+
list(cred) [#]
+
+

List the records in an authority. The objectGID in the supplied credential +should name the authority that will be listed. + +TODO: List doesn't take an hrn and uses the hrn contained in the + objectGid of the credential. Does this mean the only way to list an + authority is by having a credential for that authority?

+
+
cred
+
+credential string specifying rights of the caller
+
Returns:
+
+list of record dictionaries
+

+
+
lookup_users(auth_table, user_id_list, role="*") [#]
+
+

Look up user records given PLC user-ids. This is used as part of the +process for reverse-mapping PLC records into Geni records.

+
+
auth_table
+
+database table for the authority that holds the user records
+
user_id_list
+
+list of user ids
+
role
+
+either "*" or a string describing the role to look for ("pi", "user", ...) + +TODO: This function currently only searches one authority because it would +be inefficient to brute-force search all authorities for a user id. The +solution would likely be to implement a reverse mapping of user-id to +(type, hrn) pairs.
+

+
+
record_to_slice_info(record) [#]
+
+

Convert a PLC record into the slice information that will be stored in +a ticket. There are two parts to this information: attributes and +rspec. + +Attributes are non-resource items, such as keys and the initscript +Rspec is a set of resource specifications

+
+
record
+
+a record object
+
Returns:
+
+a tuple (attrs, rspec) of dictionaries
+

+
+
register(cred, record_dict) [#]
+
+

GENI API: register + +Register an object with the registry. In addition to being stored in the +Geni database, the appropriate records will also be created in the +PLC databases

+
+
cred
+
+credential string
+
record_dict
+
+dictionary containing record fields
+

+
+
register_functions() [#]
+
+

Register the server RPCs for the registry

+
+
remove(cred, record_dict) [#]
+
+

GENI API: remove + +Remove an object from the registry. If the object represents a PLC object, +then the PLC records will also be removed.

+
+
cred
+
+credential string
+
record_dict
+
+dictionary containing record fields. The only relevant + fields of the record are 'name' and 'type', which are used to lookup + the current copy of the record in the Geni database, to make sure + that the appopriate record is removed.
+

+
+
resolve(cred, name) [#]
+
+

GENI API: Resolve + +This is a wrapper around resolve_raw that converts records objects into +dictionaries before returning them to the user.

+
+
cred
+
+credential string authorizing the caller
+
name
+
+human readable name to resolve
+
Returns:
+
+a list of record dictionaries, or an empty list
+

+
+
resolve_raw(type, name, must_exist=True) [#]
+
+

Resolve a record. This is an internal version of the Resolve API call +and returns records in record object format rather than dictionaries +that may be sent over XMLRPC.

+
+
type
+
+type of record to resolve (user | sa | ma | slice | node)
+
name
+
+human readable name of object
+
must_exist
+
+if True, throw an exception if no records are found
+
Returns:
+
+a list of record objects, or an empty list []
+

+
+
update(cred, record_dict) [#]
+
+

GENI API: Register + +Update an object in the registry. Currently, this only updates the +PLC information associated with the record. The Geni fields (name, type, +GID) are fixed. + +The record is expected to have the pl_info field filled in with the data +that should be updated. + +TODO: The geni_info member of the record should be parsed and the pl_info +adjusted as necessary (add/remove users from a slice, etc)

+
+
cred
+
+credential string specifying rights of the caller
+
record
+
+a record dictionary to be updated
+

+
+
verify_auth_belongs_to_me(name) [#]
+
+

Verify that an authority belongs to this registry. This is basically left +up to the implementation of the hierarchy module. If the specified name +does not belong to this registry, an exception is thrown indicating the +caller should contact someone else.

+
+
auth_name
+
+human readable name of authority
+

+
+
verify_object_belongs_to_me(name) [#]
+
+

Verify that an object belongs to this registry. By extension, this implies +that the authority that owns the object belongs to this registry. If the +object does not belong to this registry, then an exception is thrown.

+
+
name
+
+human readable name of object
+

+
+
verify_object_permission(name) [#]
+
+

Verify that the object_gid that was specified in the credential allows +permission to the object 'name'. This is done by a simple prefix test. +For example, an object_gid for planetlab.us.arizona would match the +objects planetlab.us.arizona.slice1 and planetlab.us.arizona.

+
+
name
+
+human readable name to test
+

+
+
+