How-to guides
=============

These guides provide instructions for performing different operations related to Simple Streams.

Install Simple Streams client
-----------------------------

The client is available as a snap and can be installed via:

.. code::

   sudo snap install simplestreams

To verify that the client got installed and works as expected,
do a query against the Cloud images release stream mirror:

.. code::

   simplestreams.sstream-query http://cloud-images.ubuntu.com/releases/

This will output lots of data.

Using the Simple Streams client
-------------------------------

The installed client (in this example from the snap) is required for those examples.
In the following examples, the Cloud release stream is used.
To query all available images on a given stream, do:

.. code::

   simplestreams.sstream-query http://cloud-images.ubuntu.com/releases/

Filtering can be done on any key available:

.. code::

   simplestreams.sstream-query http://cloud-images.ubuntu.com/releases/ \
       content_id=com.ubuntu.cloud:released:download \
       release=noble \
       arch=arm64 \
       version_name=20240725

This filters by `content_id`, `release`, `arch` and `version_name`.

.. note::

   The filtering here happens on a flattened data structure where all the keys are
   available on each `item`. Eg. the `version_name` (which contains multiple `item`)
   is available for all `item` entries. So a single `item` looks like:

   .. code::

      {'aliases': '24.04,n,noble,lts,default',
       'arch': 'arm64',
       'content_id': 'com.ubuntu.cloud:released:aws-cn',
       'crsn': 'cn-northwest-1',
       'datatype': 'image-ids',
       'endpoint': 'https://ec2.cn-northwest-1.amazonaws.com.cn',
       'format': 'products:1.0',
       'id': 'ami-0f96782d49a92cfc9',
       'item_name': 'cnnw1hg',
       'label': 'release',
       'license': 'https://ubuntu.com/legal/intellectual-property-policy',
       'os': 'ubuntu',
       'product_name': 'com.ubuntu.cloud:server:24.04:arm64',
       'pubname': 'ubuntu-noble-24.04-arm64-server-20240725',
       'region': 'cn-northwest-1',
       'release': 'noble',
       'release_codename': 'Noble Numbat',
       'release_title': '24.04 LTS',
       'root_store': 'ssd-gp3',
       'support_eol': '2029-05-31',
       'supported': 'True',
       'updated': 'Tue, 30 Jul 2024 04:53:12 +0000',
       'version': '24.04',
       'version_name': '20240725',
       'virt': 'hvm'}

Another option is eg. to filter by `version_name`:

.. code::

   simplestreams.sstream-query --pretty http://cloud-images.ubuntu.com/releases/ version_name=20240725

This will print out all items with a `version_name=20240725`. Note that this includes items
from all products listed in the `index.sjson` which have that `version_name`. That's cross product
filtering is very useful to query for common attributes over different products.