A dream comes true; a smartphone focused on security and privacy and fully based on open source technology.

This is what the Purism Librem 5 is planned to become: the first smartphone completely build on top of open source software and open source compatible hardware. Lately the project got a lot of attention as of KDE and GNOME announcing their partnership with Purism for the Librem 5.

As the fund raising campaign for the Librem 5 is still in need for backers it’s now up to all those...

Well it’s been many many years and many many releases that we’ve been carrying a large number of patches for the cloud-init package in openSUSE and SUSE Linux Enterprise. I remember the first semi serious implementation of SLES support happened when I worked with HP to get SLES into the HP Public Cloud offering, which was based on OpenStack. The offer was eventually named Helion Public Cloud and then eventually shut down. Yes, it’s been many many years and I have received many questions about when is SUSE support going to be upstreamed, and my answer was always, “when I get around to it“. Well, it finally happened, in big part thanks to the cloud-init summit which was held for the first time earlier this year. Google in Seattle was a great host and I very much appreciate that I was invited.

Anyway, long story short spending some face time with other contributors and working out the kinks that existed in the pipeline worked wonders.  Rather than sending a small patch here and there the main implementation for openSUSE and SLE, lots of code, were accepted shortly after the cloud-init summit and over the last couple of days another couple of patches took us another step forward.

There are a few more loose ends that need work but with 17 patches removed from the package build, currently building in Cloud:Tools:Next in OBS we’ve made major progress.

Well, I for one am happy about this, and those that want to install from source can do so and have openSUSE and SLE support working from the upstream sources and not just from the packages included with openSUSE and SLE.

Thanks to Canonical for organizing the summit to get everyone together and thanks to Google for hosting the summit.

Oh and before I forget, getting the changes accepted was not the only major step forward, openSUSE Leap 42.3 will, in the not too distant future, like in the next couple of days, be integrated into cloud-init testing using containers the lxd project builds, go figure who knew these even existed.

I had to apply a fix for a FCoE module in YaST, and I had no idea.

After learning a couple of things I still only have a vague idea, but I am writing it down to help my future self, my team mates, and perhaps you too.

FCoE stands for "Fibre channel over Ethernet". Apparently if you have some disk on a Fibre Channel SAN (storage area network), you can use FCoE to extend the reachability of that disk to the ethernet parts of your network. It still needs to be a kind of special ethernet (10Gb, with special network cards) but that seems less special than FC hardware.

For a better overview, including a diagram, see: SUSE Linux Enterprise Server Documentation / Storage Administration Guide / Fibre Channel Storage over Ethernet Networks: FCoE.

FCoE typically uses a virtual LAN, (VLAN, IEEE 802.1Q).

There needs to be a Fibre Channel Forwarder (FCF) between the FC and ethernet parts. It has a MAC address. Note a difference from iSCSI which works on the IP level, one layer up.

YaST helps you set things up. The rest of this article could be useful if you cannot use YaST for some reason.

SLES uses open-fcoe. On SLES-12 the package is called fcoe-utils.

fipvlan (stands for FCoE Initialization Protocol VLAN discovery) shows FCFs and which interface and VLAN they are reachable with:

# fipvlan --auto
Fibre Channel Forwarders Discovered
interface       | VLAN | FCF MAC
------------------------------------------
eth1            | 500  | 00:0d:ec:b3:ca:00

It can also --create the VLAN interface and --start up the FCoE connection, but it won't make that permanent for the next boot

To make it permanent you need to

1. enable the FCoE service (SLE11:/etc/init.d/boot.fcoe, SLE12: fcoe.service). Under the hood it uses two programs: fcoemon is the daemon, fcoeadm is a front end (fcoeadm -p shows the pid of fcoemon).
2. write a config file, /etc/fcoe/cfg-*IFACE*, where IFACE is
   • eth1.500 if AUTO_VLAN is no; in this case, you also need /etc/sysconfig/network/ifcfg-eth1.500, see man ifcfg-vlan.
   • eth1 if AUTO_VLAN is yes; in this case, the interface is named eth1.500-fcoe. Note the unusual -fcoe suffix!

With the config files in place, rcfcoe start (and ifup eth1.500, unless AUTO_VLAN). Then you should see the disk devices:

# fcoeadm --target
    Interface:        eth1.500
    Roles:            FCP Target
    Node Name:        0x50060160BB600160
    Port Name:        0x500601663B600160
    Target ID:        0
    MaxFrameSize:     2048
    OS Device Name:   rport-2:0-2
    FC-ID (Port ID):  0x710D00
    State:            Online

    LUN ID  Device Name   Capacity   Block Size  Description
    ------  -----------  ----------  ----------  ----------------------------
         0  /dev/sdb      16.00 GiB      512     DGC VRAID (rev 0430)
[...]

People who actually know their way around FCoE will note that I have omitted many important details. Let me know in the comments whether I should come back to this and expand on some topics.

If you are used to handling activities with administrator rights (“root”) like I am from the Debian world, you will have some difficulties with openSUSE in the beginning. With two users it is still possible, because you can set the same password for both user and root. But at the latest with more user accounts this is already over, unless you give the root password to everyone. Both solutions are certainly somehow practicable, but it’s not very nice. Especially since sudo would actually be installed – but only halfway through.

So I started with my current openSUSE Tumbleweed to teach the system a reasonable sudo concept and then apply it to YaST. It was a bit nasty to find out, but in the end it worked well.

Let’s go!

visudo

By default sudo asks for the root password. This is pretty nonsensical, so let’s change it!

1. In the first part we still work as normal users. The line details may vary depending on the age of the file/system version and previous changes to it.
   

   sudo visudo

2. The parameters in line 43 starting with env_keep = “LANG… at the end within the quotation marks:
   

   DISPLAY XAUTHORITY

3. Comment out lines 68 and 69 completely, so that the password of the “target user” is no longer requested:
   

   #Defaults       targetpw
   #ALL    ALL = (ALL) ALL

4. Additionally you uncomment line 81, so delete the comment character #:
   

   %wheel ALL=(ALL) ALL

5. Save, close and then add your user(s) to the group “wheel” either via YaST or directly in the terminal:
   

   gpasswd -a <dein-username> wheel

   By logging out and in again, the change will be applied and sudo wants to have your user password in the terminal from now on.

YaST

For the graphical version of YaST, PolicyKit is used for authentication, a little more work is needed here. From here on, you work as root, so change the account with su –.

1. Create a PolicyKit Action for YaST
   

   vim /usr/share/polkit-1/actions/org.opensuse.pkexec.yast2.policy

2. Insert the following XML block into the file. Please pay attention to line breaks when copying/pasting.
   

   <?xml version="1.0" encoding="UTF-8"?><!DOCTYPE policyconfig PUBLIC "-//freedesktop//DTD PolicyKit Policy Configuration 1.0//EN" "http://www.freedesktop.org/software/polkit/policyconfig-1.dtd">
   <policyconfig>
   
     <action id="org.opensuse.pkexec.yast2">
       <message>Authentication is required to run YaST2</message>
       <icon_name>yast2</icon_name>
       <defaults>
         <allow_any>auth_self</allow_any>
         <allow_inactive>auth_self</allow_inactive>
         <allow_active>auth_self</allow_active>
       </defaults>
       <annotate key="org.freedesktop.policykit.exec.path">/usr/sbin/yast2</annotate>
       <annotate key="org.freedesktop.policykit.exec.allow_gui">true</annotate>
     </action>
   
   </policyconfig>

   Save, close – the success can be checked as a regular user with pkexec /usr/sbin/yast2.

3. Save the default rights configuration and replace it with the system configuration. Our file will not be overwritten during an upgrade.
   

   mv /etc/polkit-default-privs.local /etc/polkit-default-privs.local.bkup
   cp /etc/polkit-default-privs.standard /etc/polkit-default-privs.local

   The necessary adjustment is to replace auth_admin with auth_self everywhere. You can also do this by hand, but with sed it is more convenient and faster:
   

   sed -i 's/auth_admin/auth_self/g' /etc/polkit-default-privs.local

4. To make the authentication via PolicyKit work, create a short shell script that will be called from the menu in the future:
   

   vim /usr/local/sbin/yast2_polkit

5. The script looks like this, just add it to the yast2_polkit file:
   

   #!/bin/bash
   
   if [ $(which pkexec) ]; then
           pkexec --disable-internal-agent "/usr/sbin/yast2" "$@"
   else
           /usr/sbin/yast2 "$@"
   fi

6. Save and close. Finally you make the script executable:

   chmod +x /usr/local/sbin/yast2_polkit

7. Finally, you create a .desktop file. This will make the modified YaST starter appear directly in the main menu, system-wide for all users. For example, in Xfce it is listed under “Settings”. I have not tested other desktops, but I assume that the starter will end up in a useful place, since it is only a customized copy of the original.
   Of course you could also edit the original file for YaST (YaST.desktop) but it will be overwritten during an upgrade. And a copy in /usr/local/share/applications ignores both the application and whisker menus.
   So:

   vim /usr/share/applications/YaST2.desktop

8. Insert and save:
   

   [Desktop Entry]
   X-SuSE-translate=true
   Type=Application
   Categories=Settings;System;X-SuSE-Core-System;X-SuSE-ControlCenter-System;X-GNOME-SystemSettings;
   Name=YaST2
   Icon=yast
   GenericName=Administrator Settings
   Exec=/usr/local/sbin/yast2_polkit
   Encoding=UTF-8
   Comment=Manage system-wide settings
   Comment[DE]=Systemweite administrative Einstellungen
   NoDisplay=false

That’s all. With this, a login as root is no longer necessary or can be done comfortably via sudo su – with your user password. Whether the concept of openSUSE is now worse or better, I don’t want to decide. That is a matter of taste, I think.
What I liked in any case is the clear adherence to standards. This makes finding solutions much easier and faster. Thanks to good documentation and helpful forum posts I was able to finish everything within about an hour – and the great knowledge of PolicyKit!

(First part of the series, with index to all the articles)

Now let's get on and see how glib-rs handles boxed types.

Boxed types?

Let's say you are given a sealed cardboard box with something, but you can't know what's inside. You can just pass it on to someone else, or burn it. And since computers are magic duplication machines, you may want to copy the box and its contents... and maybe some day you will get around to opening it.

That's a boxed type. You get a pointer to something, who knows what's inside. You can just pass it on to someone else, burn it — I mean, free it — or since computers are magic, copy the pointer and whatever it points to.

That's exactly the API for boxed types.

typedef gpointer (*GBoxedCopyFunc) (gpointer boxed);
typedef void (*GBoxedFreeFunc) (gpointer boxed);

GType g_boxed_type_register_static (const gchar   *name,
                                    GBoxedCopyFunc boxed_copy,
                                    GBoxedFreeFunc boxed_free);

Simple copying, simple freeing

Imagine you have a color...

typedef struct {
    guchar r;
    guchar g;
    guchar b;
} Color;

If you had a pointer to a Color, how would you copy it? Easy:

Color *copy_color (Color *a)
{
    Color *b = g_new (Color, 1);
    *b = *a;
    return b;
}

That is, allocate a new Color, and essentially memcpy() the contents.

And to free it? A simple g_free() works — there are no internal things that need to be freed individually.

Complex copying, complex freeing

And if we had a color with a name?

typedef struct {
    guchar r;
    guchar g;
    guchar b;
    char *name;
} ColorWithName;

We can't just *a = *b here, as we actually need to copy the string name. Okay:

ColorWithName *copy_color_with_name (ColorWithName *a)
{
    ColorWithName *b = g_new (ColorWithName, 1);
    b->r = a->r;
    b->g = a->g;
    b->b = a->b;
    b->name = g_strdup (a->name);
    return b;
}

The corresponding free_color_with_name() would g_free(b->name) and then g_free(b), of course.

Glib-rs and boxed types

Let's look at this by parts. First, a BoxedMemoryManager trait to define the basic API to manage the memory of boxed types. This is what defines the copy and free functions, like above.

pub trait BoxedMemoryManager<T>: 'static {
    unsafe fn copy(ptr: *const T) -> *mut T;
    unsafe fn free(ptr: *mut T);
}

Second, the actual representation of a Boxed type:

pub struct Boxed<T: 'static, MM: BoxedMemoryManager<T>> {
    inner: AnyBox<T>,
    _dummy: PhantomData<MM>,
}

This struct is generic over T, the actual type that we will be wrapping, and MM, something which must implement the BoxedMemoryManager trait.

Inside, it stores inner, an AnyBox, which we will see shortly. The _dummy: PhantomData<MM> is a Rust-ism to indicate that although this struct doesn't actually store a memory manager, it acts as if it does — it does not concern us here.

The actual representation of boxed data

Let's look at that AnyBox that is stored inside a Boxed:

enum AnyBox<T> {
    Native(Box<T>),
    ForeignOwned(*mut T),
    ForeignBorrowed(*mut T),
}

We have three cases:

• Native(Box<T>) - this boxed value T comes from Rust itself, so we know everything about it!

• ForeignOwned(*mut T) - this boxed value T came from the outside, but we own it now. We will have to free it when we are done with it.

• ForeignBorrowed(*mut T) - this boxed value T came from the outside, but we are just borrowing it temporarily: we don't want to free it when we are done with it.

For example, if we look at the implementation of the Drop trait for the Boxed struct, we will indeed see that it calls the BoxedMemoryManager::free() only if we have a ForeignOwned value:

impl<T: 'static, MM: BoxedMemoryManager<T>> Drop for Boxed<T, MM> {
    fn drop(&mut self) {
        unsafe {
            if let AnyBox::ForeignOwned(ptr) = self.inner {
                MM::free(ptr);
            }
        }
    }
}

If we had a Native(Box<T>) value, it means it came from Rust itself, and Rust knows how to Drop its own Box<T> (i.e. a chunk of memory allocated in the heap).

But for external resources, we must tell Rust how to manage them. Again: in the case where the Rust side owns the reference to the external boxed data, we have a ForeignOwned and Drop it by free()ing it; in the case where the Rust side is just borrowing the data temporarily, we have a ForeignBorrowed and don't touch it when we are done.

Copying

When do we have to copy a boxed value? For example, when we transfer from Rust to Glib with full transfer of ownership, i.e. the to_glib_full() pattern that we saw before. This is how that trait method is implemented for Boxed:

impl<'a, T: 'static, MM: BoxedMemoryManager<T>> ToGlibPtr<'a, *const T> for Boxed<T, MM> {
    fn to_glib_full(&self) -> *const T {
        use self::AnyBox::*;
        let ptr = match self.inner {
            Native(ref b) => &**b as *const T,
            ForeignOwned(p) | ForeignBorrowed(p) => p as *const T,
        };
        unsafe { MM::copy(ptr) }
    }
}

See the MM:copy(ptr) in the last line? That's where the copy happens. The lines above just get the appropriate pointer to the data data from the AnyBox and cast it.

There is extra boilerplate in boxed.rs which you can look at; it's mostly a bunch of trait implementations to copy the boxed data at the appropriate times (e.g. the FromGlibPtrNone trait), also an implementation of the Deref trait to get to the contents of a Boxed / AnyBox easily, etc. The trait implementations are there just to make it as convenient as possible to handle Boxed types.

Who implements BoxedMemoryManager?

Up to now, we have seen things like the implementation of Drop for Boxed, which uses BoxedMemoryManager::free(), and the implementation of ToGlibPtr which uses ::copy().

But those are just the trait's "abstract" methods, so to speak. What actually implements them?

Glib-rs has a general-purpose macro to wrap Glib types. It can wrap boxed types, shared pointer types, and GObjects. For now we will just look at boxed types.

Glib-rs comes with a macro, glib_wrapper!(), that can be used in different ways. You can use it to automatically write the boilerplate for a boxed type like this:

glib_wrapper! {
    pub struct Color(Boxed<ffi::Color>);

    match fn {
        copy => |ptr| ffi::color_copy(mut_override(ptr)),
        free => |ptr| ffi::color_free(ptr),
        get_type => || ffi::color_get_type(),
    }
}

This expands to an internal glib_boxed_wrapper!() macro that does a few things. We will only look at particularly interesting bits.

First, the macro creates a newtype around a tuple with 1) the actual data type you want to box, and 2) a memory manager. In the example above, the newtype would be called Color, and it would wrap an ffi:Color (say, a C struct).

        pub struct $name(Boxed<$ffi_name, MemoryManager>);

Aha! And that MemoryManager? The macro defines it as a zero-sized type:

        pub struct MemoryManager;

Then it implements the BoxedMemoryManager trait for that MemoryManager struct:

        impl BoxedMemoryManager<$ffi_name> for MemoryManager {
            #[inline]
            unsafe fn copy($copy_arg: *const $ffi_name) -> *mut $ffi_name {
                $copy_expr
            }

            #[inline]
            unsafe fn free($free_arg: *mut $ffi_name) {
                $free_expr
            }
        }

There! This is where the copy/free methods are implemented, based on the bits of code with which you invoked the macro. In the call to glib_wrapper!() we had this:

        copy => |ptr| ffi::color_copy(mut_override(ptr)),
        free => |ptr| ffi::color_free(ptr),

In the impl aboe, the $copy_expr will expand to ffi::color_copy(mut_override(ptr)) and $free_expr will expand to ffi::color_free(ptr), which defines our implementation of a memory manager for our Color boxed type.

Zero-sized what?

Within the macro's definition, let's look again at the definitions of our boxed type and the memory manager object that actually implements the BoxedMemoryManager trait. Here is what the macro would expand to with our Color example:

        pub struct Color(Boxed<ffi::Color, MemoryManager>);

        pub struct MemoryManager;

        impl BoxedMemoryManager<ffi::Color> for MemoryManager {
            unsafe fn copy(...) -> *mut ffi::Color { ... }
            unsafe fn free(...) { ... }
        }

Here, MemoryManager is a zero-sized type. This means it doesn't take up any space in the Color tuple! When a Color is allocated in the heap, it is really as if it contained an ffi::Color (the C struct we are wrapping) and nothing else.

All the knowledge about how to copy/free ffi::Color lives only in the compiler thanks to the trait implementation. When the compiler expands all the macros and monomorphizes all the generic functions, the calls to ffi::color_copy() and ffi::color_free() will be inlined at the appropriate spots. There is no need to have auxiliary structures taking up space in the heap, just to store function pointers to the copy/free functions, or anything like that.

Next up

You may have seen that our example call to glib_wrapper!() also passed in a ffi::color_get_type() function. We haven't talked about how glib-rs wraps Glib's GType, GValue, and all of that. We are getting closer and closer to being able to wrap GObject.

Stay tuned!