mirror of
https://codeberg.org/Toasterson/ips.git
synced 2026-04-10 21:30:41 +00:00
Expand pkg5 documentation with additional details on repository operations, including administrative tasks, enhanced metadata handling, new operation versions, and improved search functionality.
This commit is contained in:
Till Wegmueller
parent
ca7ce75008
commit
01b059bf5d
1 changed files with 355 additions and 4 deletions
|
|
@ -162,6 +162,10 @@ DEPOT
|
|||
These operations alter a repository's catalog, package metadata, and
|
||||
allow storage of package content.
|
||||
|
||||
- administrative
|
||||
These operations perform administrative tasks on the repository or
|
||||
depot server.
|
||||
|
||||
2.2.2. Modes
|
||||
|
||||
Which types of operations are available is dependent on which mode the depot
|
||||
|
|
@ -202,7 +206,48 @@ DEPOT
|
|||
The contents of the file, compressed using the gzip compression
|
||||
algorithm.
|
||||
|
||||
2.2.2. Depot Operations
|
||||
Version 1:
|
||||
A GET or POST/PUT operation that retrieves or uploads the contents of a file.
|
||||
For GET requests, it behaves the same as Version 0.
|
||||
For POST/PUT requests, it allows uploading file content to the repository.
|
||||
|
||||
Example:
|
||||
URL:
|
||||
http://pkg.opensolaris.org/release/file/1/
|
||||
a00030db8b91f85d0b7144d0d4ef241a3f1ae28f
|
||||
|
||||
Expects:
|
||||
For GET: A SHA-1 hash of the file's content belonging to a package in the
|
||||
request path.
|
||||
For POST/PUT: The file content in the request body.
|
||||
|
||||
Returns:
|
||||
For GET: The contents of the file, compressed using the gzip compression
|
||||
algorithm.
|
||||
For POST/PUT: Response status of 200 on success; any other status indicates
|
||||
failure.
|
||||
|
||||
Version 2:
|
||||
Extends Version 1 to add support for HEAD requests. For GET and POST/PUT
|
||||
requests, it behaves the same as Version 1. For HEAD requests, it returns
|
||||
metadata about the file without returning the file content.
|
||||
|
||||
Example:
|
||||
URL:
|
||||
http://pkg.opensolaris.org/release/file/2/
|
||||
a00030db8b91f85d0b7144d0d4ef241a3f1ae28f
|
||||
|
||||
Expects:
|
||||
For GET/POST/PUT: Same as Version 1.
|
||||
For HEAD: A SHA-1 hash of the file's content belonging to a package in the
|
||||
request path.
|
||||
|
||||
Returns:
|
||||
For GET/POST/PUT: Same as Version 1.
|
||||
For HEAD: Response headers containing file metadata including compressed
|
||||
attributes in X-Ipkg-Attr-{n} headers.
|
||||
|
||||
2.2.4. Depot Operations
|
||||
|
||||
- versions
|
||||
Version 0:
|
||||
|
|
@ -235,7 +280,23 @@ DEPOT
|
|||
close 0
|
||||
open 0
|
||||
|
||||
2.2.2. Meta-data Operations
|
||||
- status
|
||||
Version 0:
|
||||
A GET operation that retrieves a JSON formatted dictionary containing
|
||||
statistics information for the repository being served.
|
||||
|
||||
Example:
|
||||
URL:
|
||||
http://pkg.opensolaris.org/status/0/
|
||||
|
||||
Expects:
|
||||
Nothing
|
||||
|
||||
Returns:
|
||||
A JSON formatted dictionary containing statistics information for
|
||||
the repository being served.
|
||||
|
||||
2.2.5. Meta-data Operations
|
||||
|
||||
- catalog
|
||||
Version 0:
|
||||
|
|
@ -256,6 +317,164 @@ DEPOT
|
|||
that were added since the specified date as they are found
|
||||
in the catalog file, separated by newlines.
|
||||
|
||||
Version 1:
|
||||
A GET operation that retrieves the contents of a specific catalog file
|
||||
by name.
|
||||
|
||||
Example:
|
||||
URL:
|
||||
http://pkg.opensolaris.org/catalog/1/catalog.attrs
|
||||
|
||||
Expects:
|
||||
A catalog file name in the request path.
|
||||
|
||||
Returns:
|
||||
The contents of the specified catalog file.
|
||||
|
||||
Valid Catalog File Names:
|
||||
The following catalog files are valid for the V1 catalog endpoint:
|
||||
|
||||
catalog.attrs
|
||||
Contains metadata about the catalog, including creation date,
|
||||
last modified date, package counts, and information about
|
||||
available catalog parts.
|
||||
|
||||
Sample Output:
|
||||
{
|
||||
"_SIGNATURE": {
|
||||
"sha-1": "8f5c22fd8218f7a0982d3e3fdd01e40671cb9cab"
|
||||
},
|
||||
"created": "20050614T080000.234231Z",
|
||||
"last-modified": "20090508T161025.686485Z",
|
||||
"package-count": 40802,
|
||||
"package-version-count": 1706,
|
||||
"parts": {
|
||||
"catalog.base.C": {
|
||||
"last-modified": "20090508T161025.686485Z",
|
||||
"signature-sha-1": "9b37ef267ae6aa8a31b878aad4e9baa234470d45"
|
||||
},
|
||||
"catalog.dependency.C": {
|
||||
"last-modified": "20090508T161025.686485Z",
|
||||
"signature-sha-1": "0c896321c59fd2cd4344fec074d55ba9c88f75e8"
|
||||
},
|
||||
"catalog.summary.C": {
|
||||
"last-modified": "20090508T161025.686485Z",
|
||||
"signature-sha-1": "b3a6ab53677c7b5f94c9bd551a484d57b54ed6f7"
|
||||
}
|
||||
},
|
||||
"version": 1
|
||||
}
|
||||
|
||||
catalog.base.C
|
||||
Contains the FMRIs of packages in the repository and optional
|
||||
digest values for verifying manifest contents.
|
||||
|
||||
Sample Output:
|
||||
{
|
||||
"_SIGNATURE": {
|
||||
"sha-1": "9b37ef267ae6aa8a31b878aad4e9baa234470d45"
|
||||
},
|
||||
"opensolaris.org": {
|
||||
"SUNWipkg": [
|
||||
{
|
||||
"version": "0.5.11,5.11-0.117:20090623T135937Z",
|
||||
"signature-sha-1": "596f26c4fc725b486faba089071d2b3b35482114"
|
||||
},
|
||||
{
|
||||
"version": "0.5.11,5.11-0.118:20090707T220625Z",
|
||||
"signature-sha-1": "ab6f26c4fc725b386faca089071d2b3d35482114"
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
|
||||
catalog.dependency.C
|
||||
Contains package FMRIs, depend actions, and set actions for
|
||||
facets or variants.
|
||||
|
||||
Sample Output:
|
||||
{
|
||||
"_SIGNATURE": {
|
||||
"sha-1": "0c896321c59fd2cd4344fec074d55ba9c88f75e8"
|
||||
},
|
||||
"opensolaris.org": {
|
||||
"SUNWdvdrw": [
|
||||
{
|
||||
"version": "5.21.4.10.8,5.11-0.108:20090218T042840Z",
|
||||
"actions": [
|
||||
"set name=variant.zone value=global value=nonglobal",
|
||||
"set name=variant.arch value=sparc value=i386",
|
||||
"depend fmri=SUNWlibms@0.5.11-0.108 type=require",
|
||||
"depend fmri=SUNWlibC@0.5.11-0.108 type=require",
|
||||
"depend fmri=SUNWcsl@0.5.11-0.108 type=require"
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
|
||||
catalog.summary.C
|
||||
Contains package FMRIs and set actions (excluding those for
|
||||
facets or variants).
|
||||
|
||||
Sample Output:
|
||||
{
|
||||
"_SIGNATURE": {
|
||||
"catalog-sha-1": "b3a6ab53677c7b5f94c9bd551a484d57b54ed6f7"
|
||||
},
|
||||
"opensolaris.org": {
|
||||
"SUNWdvdrw": [
|
||||
{
|
||||
"version": "5.21.4.10.8,5.11-0.108:20090218T042840Z",
|
||||
"actions": [
|
||||
"set name=description value=\"DVD creation utilities\"",
|
||||
"set name=info.classification value=org.opensolaris.category.2008:System/Media"
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
|
||||
catalog.summary.<locale_name>
|
||||
Locale-specific versions of the summary catalog, where
|
||||
<locale_name> is an OpenSolaris system locale name.
|
||||
|
||||
update.<logdate>.<locale_name>
|
||||
Update logs containing incremental changes to the catalog,
|
||||
where <logdate> is a UTC date and time in ISO-8601 'reduced
|
||||
accuracy basic format' and <locale_name> is an OpenSolaris
|
||||
system locale name.
|
||||
|
||||
Sample Output:
|
||||
{
|
||||
"_SIGNATURE": {
|
||||
"sha-1": "0c896321c59fd2cd4344fec074d55ba9c88f75e8"
|
||||
},
|
||||
"opensolaris.org": {
|
||||
"SUNWdvdrw": [
|
||||
{
|
||||
"op-type": "add",
|
||||
"op-time": "20090524T042841Z",
|
||||
"version": "5.21.4.10.8,5.11-0.111:20090524T042840Z",
|
||||
"catalog.dependency.C": {
|
||||
"actions": [
|
||||
"depend fmri=SUNWlibms@0.5.11-0.111 type=require",
|
||||
"depend fmri=SUNWlibC@0.5.11-0.111 type=require",
|
||||
"depend fmri=SUNWcsl@0.5.11-0.111 type=require"
|
||||
]
|
||||
},
|
||||
"catalog.summary.C": {
|
||||
"actions": [
|
||||
"set name=description value=\"DVD creation utilities\"",
|
||||
"set name=info.classification value=org.opensolaris.category.2008:System/Media"
|
||||
]
|
||||
},
|
||||
"signature-sha-1": "fe6f26c4fc124b386faca089071d2b3a35482114"
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
|
||||
- info
|
||||
Version 0:
|
||||
A GET operation that retrieves a text/plain description of a
|
||||
|
|
@ -305,6 +524,25 @@ DEPOT
|
|||
Returns:
|
||||
The contents of the package's manifest file.
|
||||
|
||||
Version 1:
|
||||
A GET or POST/PUT operation that retrieves or uploads the contents of a
|
||||
manifest file. For GET requests, it behaves the same as Version 0.
|
||||
For POST/PUT requests, it allows uploading manifest content to the repository.
|
||||
|
||||
Example:
|
||||
URL:
|
||||
http://pkg.opensolaris.org/manifest/1/entire@0.5.11,5.11-0.101:20081119T235706Z
|
||||
|
||||
Expects:
|
||||
For GET: A URL-encoded pkg(5) FMRI excluding the 'pkg:/' scheme prefix
|
||||
and publisher information and including the full version information.
|
||||
For POST/PUT: The manifest content in the request body.
|
||||
|
||||
Returns:
|
||||
For GET: The contents of the package's manifest file.
|
||||
For POST/PUT: Response status of 200 on success; any other status indicates
|
||||
failure.
|
||||
|
||||
- p5i
|
||||
Version 0:
|
||||
A GET operation that retrieves an application/vnd.pkg5.info
|
||||
|
|
@ -351,6 +589,24 @@ DEPOT
|
|||
configuration's publisher information. The Content-Type of the
|
||||
response is 'application/vnd.pkg5.info'.
|
||||
|
||||
Version 1:
|
||||
A GET operation that retrieves an application/vnd.pkg5.info
|
||||
datastream representing publisher information for a specific publisher
|
||||
or all publishers. This version provides improved error handling and
|
||||
response formatting.
|
||||
|
||||
Example:
|
||||
URL:
|
||||
http://pkg.opensolaris.org/release/publisher/1
|
||||
|
||||
Expects:
|
||||
Nothing
|
||||
|
||||
Returns:
|
||||
Returns a pkg(5) information datastream based on the repository
|
||||
configuration's publisher information. The Content-Type of the
|
||||
response is 'application/vnd.pkg5.info'.
|
||||
|
||||
- search
|
||||
Version 0:
|
||||
A GET operation that retrieves a text/plain list of packages with
|
||||
|
|
@ -381,7 +637,54 @@ DEPOT
|
|||
basename pkg:/SUNWvim@7.1.284,5.11-0.101:20081119T230659Z dir usr/share/vim
|
||||
basename pkg:/SUNWvim@7.1.284,5.11-0.93:20080708T171331Z file usr/bin/vim
|
||||
|
||||
2.2.3. Publishing Operations
|
||||
Version 1:
|
||||
A GET or POST operation that retrieves a text/plain list of packages with
|
||||
metadata that matches the specified criteria. This version adds support for
|
||||
POST requests, case-sensitive searches, and returns a validation string
|
||||
to confirm the client is talking to a valid search server.
|
||||
|
||||
Example:
|
||||
URL:
|
||||
http://pkg.opensolaris.org/release/search/1/vim
|
||||
|
||||
Expects:
|
||||
For GET: A URL-encoded token representing the search criteria.
|
||||
For POST: Search criteria in the request parameters.
|
||||
|
||||
Returns:
|
||||
A text/plain list of matching entries, preceded by a validation string.
|
||||
Each entry consists of a set of space-separated values:
|
||||
|
||||
query_number - which query in the request this result is for
|
||||
|
||||
return_type - whether the result is an action or package
|
||||
|
||||
fmri - the fmri of the package that contains the match
|
||||
|
||||
field - the field that matched (URL-encoded)
|
||||
|
||||
line - the line that matched (for actions)
|
||||
|
||||
If no results are found, a 204 No Content status is returned.
|
||||
|
||||
- index
|
||||
Version 0:
|
||||
A GET operation that provides an administrative interface for search
|
||||
indexing. Returns no output if successful; otherwise the response body
|
||||
will contain the failure details.
|
||||
|
||||
Example:
|
||||
URL:
|
||||
http://pkg.opensolaris.org/release/index/0/refresh
|
||||
|
||||
Expects:
|
||||
A command to execute, such as "refresh" to update search indexes.
|
||||
|
||||
Returns:
|
||||
No output if successful; otherwise the response body will contain
|
||||
the failure details.
|
||||
|
||||
2.2.6. Publishing Operations
|
||||
|
||||
- add
|
||||
Version 0:
|
||||
|
|
@ -429,6 +732,23 @@ DEPOT
|
|||
Response status of 200 on success; any other status indicates
|
||||
failure.
|
||||
|
||||
- append
|
||||
Version 0:
|
||||
A POST operation that starts an append transaction for the package
|
||||
name specified in the request path. Returns no output.
|
||||
|
||||
Example:
|
||||
URL:
|
||||
http://pkg.opensolaris.org/append/0/system%2Flibc@0.1-98
|
||||
|
||||
Expects:
|
||||
A URL-encoded pkg(5) FMRI (excluding timestamp).
|
||||
|
||||
Returns:
|
||||
Response status of 200 on success and an identifier for the new
|
||||
transaction in the 'Transaction-ID' response header; any other
|
||||
status indicates failure.
|
||||
|
||||
- close
|
||||
Version 0:
|
||||
A GET operation that ends an in-flight transaction for the
|
||||
|
|
@ -464,5 +784,36 @@ DEPOT
|
|||
transaction in the 'Transaction-ID' response header; any other
|
||||
status indicates failure.
|
||||
|
||||
3. References
|
||||
2.2.7. Administrative Operations
|
||||
|
||||
- admin
|
||||
Version 0:
|
||||
A GET operation that executes a specified repository administration
|
||||
operation based on the provided query string.
|
||||
|
||||
Example:
|
||||
URL:
|
||||
http://pkg.opensolaris.org/release/admin/0?cmd=refresh-index
|
||||
|
||||
Expects:
|
||||
A command parameter in the query string. Available commands are:
|
||||
rebuild
|
||||
Discard search data and package catalogs and rebuild both.
|
||||
rebuild-indexes
|
||||
Discard search data and rebuild.
|
||||
rebuild-packages
|
||||
Discard package catalogs and rebuild.
|
||||
refresh
|
||||
Update search and package data.
|
||||
refresh-indexes
|
||||
Update search data. (Add packages found in the repository
|
||||
to their related search indexes.)
|
||||
refresh-packages
|
||||
Update package data. (Add packages found in the repository
|
||||
to their related catalog.)
|
||||
|
||||
Returns:
|
||||
No output if successful; otherwise the response body will contain
|
||||
the failure details.
|
||||
|
||||
3. References
|
||||
Loading…
Add table
Reference in a new issue