doc/autoinclude/Services.doc

   1 /**
   2
   3 \page zypp-services Services
   4
   5 \author Duncan Mac-Vicar P. <dmacvicar@suse.de>
   6
   7 Services provide a list of repositories. So when the service is refreshed, the repositories specified by the service service is synced with the local repository list.
   8
   9 \section service-types Classes of services
  10
  11 There are two classes of services:
  12
  13 \subsection services-remote Remote Services
  14
  15 Remote services are a subscription to a remote server, that provide a list of repositories that will be synced with the previous list of repositories for the same service.
  16
  17 By default, the remote services list is stored in the \ref /etc/zypp/services.d directory in standard INI files. Each file can contain more than one service.
  18
  19 The format is the following:
  20
  21 \verbatim
  22 [servicealias]
  23 name=My Service
  24 url=http://customers.maintenance.company.com/service
  25 enabled=true
  26 autorefresh=true
  27 type=nu
  28 \endverbatim
  29
  30 The type "nu" stands for Novell Update, which gives a customer the repositories it is entitled to access. The type "ris" is an extended version of the "nu" type.
  31 Additionally, the file could contain "repostoenable" and "repostodisable" entries, which contain a list of repository aliases to enable or disable on the next refresh. This line is modified by other programs to force enabling or disabling a certain repository.
  32
  33 From the remote side, the service url needs to provide a repoindex.xml file with the repository list:
  34
  35 \verbatim
  36 <repoindex>
  37   <repo url="http://foo.com/repo1" alias="a repository 1"/>
  38   <repo url="http://foo.com/repo2" alias="a repository 2"/>
  39 ...
  40 </repoindex>
  41 \endverbatim
  42
  43 \subsection services-plugin Plugin Services
  44
  45 \ref plugin-services "Plugin services" are simple scripts that return a list of repositories. They are installed locally in the system using packages. For each script installed ZYpp will “see” a service of type “plugin”. When you refresh the service, the repositories this script returns as output will be added (or removed and kept in sync if they change afterwards).
  46
  47 A plugin service is a program installed in /usr/lib/zypp/plugins/services.
  48
  49 Once a program called "foobar" is installed, listing services will show it:
  50
  51 \verbatim
  52 > zypper ls
  53 #  | Alias            | Name         | Enabled | Refresh | Type
  54 ---+------------------+--------------+---------+---------+-------
  55 1  | foobar           | foobar       | Yes     | Yes     | plugin
  56 ...
  57 ...
  58 \endverbatim
  59
  60 When this service is refreshed, the program will be executed and it will return
  61 the list of repositories in the same .repo files format that can be found in
  62 /etc/zypp/repos.d:
  63
  64 \verbatim
  65 # output returned by the plugin
  66
  67 [repo-oss]
  68 name=oss
  69 enabled=1
  70 autorefresh=0
  71 baseurl=http://download.opensuse.org//distribution/11.4/repo/oss
  72 type=yast2
  73 keeppackages=0
  74
  75 ...
  76 \endverbatim
  77
  78 As you can see, the main advantage of plugin services is that they can read information from the client and calculate the repository list from there. Nothing prevents a plugin service to still interact with a server to get the repository list.
  79
  80 The main disadvantage is that you have logic in the client side that in case of bugs or changes, needs to be updated.
  81
  82 Spacewalk integration is implemented using plugin services. The plugin talks XML-RPC to the server and asks for the list of channels the system is subscribed to. The plugin needs to read the server address and perform the login.
  83
  84 However, the spacewalk plugin service does have an extra indirection, as the repository list returned are not plain urls, but urls of the type plugin:$name?params, which use the urlresolver plugin to get the real url. This is not necessary, and here it is done because it allows to add custom headers to the HTTP requests. You can read more about urlresolver plugins \ref plugin-url-resolver here.
  85
  86 \section service-refresh Refreshing services
  87
  88 Using zypper, you can refresh services by executing
  89
  90 \verbatim
  91 zypper refs
  92 \endverbatim
  93
  94 The repositories that are listed in the service will be added, using the reposotiy alias specified in the service index prefixed by the service alias: e.g. "myservice:myrepository". Repositories that vanished from the service will be automatically removed.
  95
  96 \section service-examples Example usecases
  97
  98 \subsection services-usecase-1 Usecase #1: The project with multiple repositories and layers
  99
 100 Imagine the following usecase (with this one I am using some real request from our KDE guys)
 101
 102 The build service provides a KDE4 repository. Which in turn requires the Qt4 repository, because is built on openSUSE 11.0 + the new Qt4 repo.
 103
 104 When looking at this problem, repository dependencies is what comes to head in the first place. But forget about them. If package dependencies are complicated right now, imagine adding a secondary (and duplicated) layer of information. Packages already know their dependencies.
 105
 106 Now imagine our KDE guys can provide an URL, which you add to zypper. And this url returns a dynamic list of repositories. And zypper adds and remove repositories based on the information returned by this url on every refresh.
 107
 108 \subsection services-usecase-2 Usecase #2: Update repositories based on the customer
 109
 110 This is actually where services where originated. Services were present in Novell ZenWorks. How it works?
 111
 112 The service url nu.novell.com is added to the system. But in this url also a customer id is present as a http username. When you registered, Novell knows the subscription and products this system is linked to and what entitlements the customer has. The service can then return a dynamic list of repositories based on the customer preferences, products and entitlements. The customer does not need to keep them manually in sync.
 113
 114 Now that we don’t have Zenworks in the base system, we still want this cool functionality for our customers, therefore ZYpp now implements services natively.
 115
 116 Technically, this even allows us to offer hotfixes to L3 supported customers on the fly: the system is marked on the server side as being hotfixed, and an extra temporary repository with the PTF (Problem Temporary Fix) packages is added to this system list of repositories.
 117
 118 \subsection services-usecase-3 Usecase #3: Dynamic repository collections
 119
 120 You are a build service user, and you have an account, and of course you have a list of watched projects you are interested to. What if you could keep your system repositores in sync with your watched project list.
 121
 122 Or what if the build service could offer a service based on keywords or other data: like http://build.opensuse.org/services/mostpopular/repo/repoindex.xml would contain dynamically the 15 most popular repositories. You add that service, and then ZYpp does the work for you of adding new popular repositories, and remove the old ones.
 123
 124 \section service-impl Developers: Implementation
 125
 126 Services are implemented in the following classes:
 127
 128 - \ref zypp::repo::ServiceType (Service types enumeration)
 129 - \ref zypp::parser::ServiceFileReader (.service file parser)
 130 - \ref zypp::ServiceInfo Information about a service (.service file data)
 131 - \ref zypp::repo::PluginServices (Services as plugins)
 132 - \ref zypp::parser::RepoindexFileReader (NU and RIS remote service index XML parser)
 133 - \ref zypp::repo::ServiceRepos (Repositories in a service)
 134
 135
 136 */