Skip to content

Commit

Permalink
Merged master to storage-ng branch
Browse files Browse the repository at this point in the history
  • Loading branch information
@shundhammer
shundhammer committed Jul 5, 2017
2 parents 144c264 + bc707bc commit 5a396a1
Show file tree
Hide file tree
Showing 47 changed files with 1,446 additions and 1,266 deletions.
42 changes: 3 additions & 39 deletions .gitignore
View file
@@ -1,41 +1,5 @@
Makefile
/Makefile.am
Makefile.in
aclocal.m4
autom4te.cache
config.cache
config.guess
config.h
config.h.in
config.log
config.status
config.sub
configure
configure.ac
depcomp
install-sh
*.pot
libtool
ltconfig
ltmain.sh
missing
mkinstalldirs
stamp-h*
Makefile.am.common
*.ami
*.bz2
.dep
tmp.*
*.log
*.ybc
POTFILES
/doc/autodocs
!/doc/autodocs/Makefile.am
home*:*
*.sw?
*.exp
*.sh
.yardoc
*.bz2
*.pot
/coverage
/test-driver
test/*.trs
/doc/autodocs
54 changes: 54 additions & 0 deletions doc/control-file.md
View file
Expand Up @@ -798,13 +798,28 @@ Section *supported\_desktops* contains list of one or more
System Roles, if defined in the control file, are presented during
the first stage of the installation. The user will select one of them
and they will affect the proposed configuration of Partitioning and Software.
It also allows to modify configuration of Systemd Services.

A role can also define additional dialogs that are shown when a given role is
selected. It is a common installation dialog with *Abort*, *Cancel* and *Next*
buttons. It supports and uses all parameters from the **GetInstArgs** module.
When going back, it will first show the last additional dialog and when going
back through all additional dialogs, it will show again the roles selection.

System roles by default preselect first defined entry unless user set it.
If the first role has an attribute *no_default* then no role will be
preselected.

Example snippet for no\_default:
```xml
<system_roles config:type="list">
<system_role>
<id>plain</id>
<no_default config:type="boolean"> true </no_default>
</system_role>
<system_roles>
```

They were requested in FATE#317481 and they are an evolution of the earlier
concept of Server Scenarios used in SLE 11.

Expand All @@ -822,13 +837,25 @@ Example:

<system_role>
<id>virtualization_host_kvm</id>
<!-- partitioning override -->
<partitioning>
<proposal_lvm config:type="boolean">true</proposal_lvm>
</partitioning>
<!-- software override -->
<software>
<default_patterns>base Minimal kvm_server</default_patterns>
</software>
<!-- few additional dialogs needed for this role -->
<additional_dialogs>kvm_setup,virt_manager_setup </additional_dialogs>
<!-- enable few additional services -->
<services config:type="list">
<service>
<name>salt-minion</name>
</service>
<service>
<name>devil-master</name>
</service>
</services>
</system_role>
</system_roles>

Expand Down Expand Up @@ -871,6 +898,9 @@ section, identified by a matching *id* element. The contents of *partitioning*
and *software* are merged with the corresponding top-level definitions. See
[Partitioning](#partitioning) and [Software](#software).

The *services* part currently supports only enabling additional services which
is done by specifying *service* with its *name* as seen in the example.

### System Scenarios

System scenarios contain definition of dialog *inst\_scenarios* in the
Expand Down Expand Up @@ -991,6 +1021,30 @@ property should be set to _true_. This works only for Btrfs root
filesystems. If another root filesystem type is chosen, this might fail
silently.

*home_path* (string) is the path (mount point) for the home
partition or volume, if any is created (depending on *try_separate_home*,
*limit_try_home* and available disk space).

By default, this is "/home". This can be set to another value like "/data", in
which case the same partitioning proposal logic (including the other _home_
parameters in this control.xml file) will be used as for "/home", just for
"/data" as the mount point, and "/home" will be on the root filesystem again
(with its own subvolume if Btrfs is used). Notice that you cannot have both a
separate "/home" and a separate "/data" with this mechanism.

**NOTICE:**

_This "home_path" parameter is a hack, introduced to make a feature possible
against all odds at the very latest stages of CaaSP 1.0 development without
breaking the entire storage proposal logic._

It is strongly advised not to use this in general. This documentation only
exists for the sake of completeness, not as an encouragement to use this
parameter.

Please contact the YaST team if you feel you need this.



#### Subvolumes

Expand Down
180 changes: 180 additions & 0 deletions doc/installer_extension.md
View file
@@ -0,0 +1,180 @@
# Modifying the Installation by an Add-on

The YaST installation workflow can be easily changed or extended by add-ons.

## Configuring the Add-on Metadata

The product package on the add-on medium (usually a `*-release` RPM package)
should link to a package providing the installer extension by a
`Provides: installerextension(<package_name>)` dependency.

That referenced package should contain the `installation.xml` file and optionally
the `y2update.tgz` archive in the root directory. The package should never
be installed into system, it is used just to provide the temporary data for the
installer. After the installation is finished the files are not needed anymore.

## Modifying the Installation Workflow

This `installation.xml` example has two parts:

- The first part adds a new step into the add-on installation workflow in already
installed system.
- The second part adds a new step into the initial installation workflow.

```xml
<?xml version="1.0"?>
<productDefines xmlns="http://www.suse.com/1.0/yast2ns" xmlns:config="http://www.suse.com/1.0/configns">
<workflows config:type="list">
<!-- Installation on a running system -->
<workflow>
<stage>normal</stage>
<mode>installation,normal</mode>

<defaults>
<enable_back>no</enable_back>
<enable_next>no</enable_next>
</defaults>

<modules config:type="list">
<module>
<label>Extension Configuration</label>
<name>testing_extension</name>
<execute>inst_testing_extension</execute>
<enable_back>yes</enable_back>
<enable_next>yes</enable_next>
</module>
</modules>
</workflow>
</workflows>

<update>
<workflows config:type="list">
<workflow>
<defaults>
<enable_back>yes</enable_back>
<enable_next>yes</enable_next>
</defaults>

<!-- First Stage Installation -->
<stage>initial</stage>
<mode>installation</mode>

<!-- Insert new steps -->
<insert_modules config:type="list">
<insert_module>
<before>system_role</before>
<modules config:type="list">
<module>
<label>Extension Configuration</label>
<name>testing_extension</name>
<!-- Name of the executed file without the .rb extension -->
<execute>inst_testing_extension</execute>
</module>
</modules>
</insert_module>
</insert_modules>
</workflow>
</workflows>
</update>
</productDefines>
```

## Adding a New System Role

This `installation.xml` example adds a new role:

```xml
<?xml version="1.0"?>
<productDefines xmlns="http://www.suse.com/1.0/yast2ns" xmlns:config="http://www.suse.com/1.0/configns">
<update>
<system_roles>
<insert_system_roles config:type="list">
<insert_system_role>
<system_roles config:type="list">
<system_role>
<id>mail_role</id>
<software>
<default_patterns>base Minimal mail_server</default_patterns>
</software>
</system_role>
</system_roles>
</insert_system_role>
</insert_system_roles>
</system_roles>
</update>

<!-- Don't forget to add the texts -->
<texts>
<mail_role>
<label>Testing Extension Role</label>
</mail_role>
<mail_role_description>
<label>• Mail server software pattern
• This is just an example!</label>
</mail_role_description>
</texts>
</productDefines>
```

In this case it just configures the default software patterns but it is possible
to define any other defaults like partitioning, etc...

## Adding New YaST Code

The installer extension package can optionally contain `y2update.tgz` archive
with executable YaST code in the usual directory structure. E.g. the clients are
read from the `/usr/share/YaST2/clients` directory in the archive.

### YaST Client Example

Here is a trivial example client which just displays a pop up dialog with a message:

```ruby
module Yast
class TestingExtensionClient < Client
include Yast::I18n

def initialize
textdomain "testing-extension"
Yast.import("Popup")
end

def main
# TRANSLATORS: A popup message
Popup.Message(_("This is an inserted step from the testing-extension addon."\
"\n\nPress OK to continue."))
return :auto
end
end
end

Yast::TestingExtensionClient.new.main
```

Save this file to `usr/share/YaST2/clients/inst_testing_extension.rb` file (including
the directory structure) and then create the `y2update.tgz` archive with command

```
tar cfzv y2update.tgz usr
```

and include it in the installer extension RPM package.

# An Example Add-on

A minimalistic but complete example add-on can be found in the [YaST:extension](
https://build.opensuse.org/project/show/YaST:extension) OBS project.

The [testing-extension-release package](
https://build.opensuse.org/package/show/YaST:extension/testing-extension-release)
links to the installer extension using `Provides:
installerextension(testing-extension-installation)`.

The [testing-extension-installation package](
https://build.opensuse.org/package/show/YaST:extension/testing-extension-installation)
contains the `installation.xml` file which defines an additional role and
adds a new installation step before the role selection dialog. The new installation
step is defined in the included `y2update.tgz` file.

![Example Extension](
https://cloud.githubusercontent.com/assets/907998/24544095/48e4e2d0-1602-11e7-8081-4c35bcf90069.gif)
42 changes: 42 additions & 0 deletions doc/system-role-handlers.md
View file
@@ -0,0 +1,42 @@
# System Role Handlers

This is a mechanism that allows to execute specific code depending on the system
role selected during the installation which was introduced in version 3.2.21
(originally in 3.1.217.20 in the `SLE-12-SP2-CASP` branch).

If you prefer, you could think of them as *hooks for system roles*.

## Types of handlers

Currently only one type of handlers exist: `finish`. Those handlers will be
executed through the
[roles_finish](https://github.com/yast/yast-installation/blob/master/src/lib/installation/clients/roles_finish.rb)

## Defining a new handler

Handlers are just plain classes which implement a `run` method and live in the
`lib/y2system_role_handlers`. The name of the file/class depends on the type of
handler they implement.

For instance, if you want to define a *finish* handler for an *ExampleRole* role,
just drop a file like this into `lib/y2system_role_handlers`.

```ruby
module Y2SystemRoleHandlers
class ExampleRoleFinish
def run
# Handler implementation goes here
end
end
end

```

The `run` method won't receive any argument and is also not expected to return
any special value. Finally, exceptions will be handled like any other YaST
exception.

## Examples

Please, check out the [yast2-caasp package](https://github.com/yast/yast-caasp)
for examples.

0 comments on commit 5a396a1

Please sign in to comment.