[Buildroot] [PATCH 1/2] docs/manual: introduce "Integration topics" chapter

[Buildroot] [PATCH 1/2] docs/manual: introduce "Integration topics" chapter

[Arnout Vandecappelle (Essensium/Mind)]

We want to add more information in the manual about how a system created
with buildroot works overall. We currently already have a chapter about
SELinux, but we want to add more information like that, e.g. details
about how systemd in Buildroot works.

Create a new chapter "Integration topics" with an introductory blurb,
and move the SELinux topic under it (as a section rather than a
chapter).

"Integration topics" is not the best title, but we couldn't find
anything better.

Signed-off-by: Arnout Vandecappelle (Essensium/Mind) <arnout@mind.be>
---
 ...x-support.txt => integration-selinux-support.txt} |  6 +++---
 docs/manual/integration.txt                          | 12 ++++++++++++
 docs/manual/manual.txt                               |  2 ++
 3 files changed, 17 insertions(+), 3 deletions(-)
 rename docs/manual/{selinux-support.txt => integration-selinux-support.txt} (96%)
 create mode 100644 docs/manual/integration.txt

diff --git a/docs/manual/selinux-support.txt b/docs/manual/integration-selinux-support.txt
similarity index 96%
rename from docs/manual/selinux-support.txt
rename to docs/manual/integration-selinux-support.txt
index 21137ae6c3..1f6bcf47eb 100644
--- a/docs/manual/selinux-support.txt
+++ b/docs/manual/integration-selinux-support.txt
@@ -2,7 +2,7 @@
 // vim: set syntax=asciidoc:
 
 [[selinux]]
-== Using SELinux in Buildroot
+=== Using SELinux in Buildroot
 
 https://selinuxproject.org[SELinux] is a Linux kernel security module
 enforcing access control policies. In addition to the traditional file
@@ -30,7 +30,7 @@ upstream https://github.com/SELinuxProject/refpolicy[refpolicy]
 project, enabled with +BR2_PACKAGE_REFPOLICY+.
 
 [[enabling-selinux]]
-=== Enabling SELinux support
+==== Enabling SELinux support
 
 To have proper support for +SELinux+ in a Buildroot generated system,
 the following configuration options must be enabled:
@@ -42,7 +42,7 @@ In addition, your filesystem image format must support extended
 attributes.
 
 [[selinux-policy-tweaking]]
-=== SELinux policy tweaking
+==== SELinux policy tweaking
 
 The +SELinux refpolicy+ contains modules that can be enabled or
 disabled when being built. Each module provide a number of +SELinux+
diff --git a/docs/manual/integration.txt b/docs/manual/integration.txt
new file mode 100644
index 0000000000..bdfbfa59de
--- /dev/null
+++ b/docs/manual/integration.txt
@@ -0,0 +1,12 @@
+// -*- mode:doc; -*-
+// vim: set syntax=asciidoc:
+
+[[integration]]
+== Integration topics
+
+This chapter discusses how various things are integrated at system
+level. Buildroot is highly configurable, almost everything discussed
+here can be changed or overridden by xref:rootfs-custom[rootfs overlay
+or custom skeleton] configuration.
+
+include::integration-selinux-support.txt[]
diff --git a/docs/manual/manual.txt b/docs/manual/manual.txt
index b5cc044805..8ba0c76d32 100644
--- a/docs/manual/manual.txt
+++ b/docs/manual/manual.txt
@@ -38,6 +38,8 @@ include::common-usage.txt[]
 
 include::customize.txt[]
 
+include::integration.txt[]
+
 include::selinux-support.txt[]
 
 include::faq-troubleshooting.txt[]
-- 
2.35.3

_______________________________________________
buildroot mailing list
buildroot@buildroot.org
https://lists.buildroot.org/mailman/listinfo/buildroot

[Buildroot] [PATCH 2/2] docs/manual: add integration section for systemd with dbus

[Arnout Vandecappelle (Essensium/Mind)]

Add a section to the "Integration topics" chapter about how we integrate
systemd. Add a first subsection about how dbus and dbus-broker work with
systemd.

This is just the start of the integration information about systemd.

Signed-off-by: Arnout Vandecappelle (Essensium/Mind) <arnout@mind.be>
---
 docs/manual/integration-systemd.txt | 27 +++++++++++++++++++++++++++
 docs/manual/integration.txt         |  2 ++
 2 files changed, 29 insertions(+)
 create mode 100644 docs/manual/integration-systemd.txt

diff --git a/docs/manual/integration-systemd.txt b/docs/manual/integration-systemd.txt
new file mode 100644
index 0000000000..44248b43ff
--- /dev/null
+++ b/docs/manual/integration-systemd.txt
@@ -0,0 +1,27 @@
+// -*- mode:doc; -*-
+// vim: set syntax=asciidoc:
+
+[[integration-systemd]]
+=== Systemd
+
+This chapter describes the decisions taken in Buildroot's integration of
+systemd, and how various use cases can be implemented.
+
+==== DBus daemon
+
+Systemd requires a DBus daemon. There are two options for it: traditional dbus
+(+BR2_PACKAGE_DBUS+) and bus1 dbus-broker (+BR2_PACKAGE_DBUS_BROKER+). At
+least one of them must be chosen. If both are included in the configuration,
+dbus-broker will be used as system bus, but the traditional dbus-daemon is
+still installed as well and can be used as session bus. Also its tools (e.g.
++dbus-send+) can be used (systemd itself has +busctl+ as an alternative). In
+addition, the traditional dbus package is the only one that provides +libdbus+,
+which is used by many packages as dbus integration library.
+
+Both in the dbus and in the dbus-broker case, the daemon runs as user +dbus+.
+The DBus configuration files are also identical for both.
+
+To make sure that only one of the two daemons is started as system bus, the
+systemd activation files of the dbus package (+dbus.socket+ and the
++dbus.service+ symlink in +multi-user.target.wants+) are removed when
+dbus-broker is selected.
diff --git a/docs/manual/integration.txt b/docs/manual/integration.txt
index bdfbfa59de..be56bf6567 100644
--- a/docs/manual/integration.txt
+++ b/docs/manual/integration.txt
@@ -9,4 +9,6 @@ level. Buildroot is highly configurable, almost everything discussed
 here can be changed or overridden by xref:rootfs-custom[rootfs overlay
 or custom skeleton] configuration.
 
+include::integration-systemd.txt[]
+
 include::integration-selinux-support.txt[]
-- 
2.35.3

_______________________________________________
buildroot mailing list
buildroot@buildroot.org
https://lists.buildroot.org/mailman/listinfo/buildroot

Re: [Buildroot] [PATCH 2/2] docs/manual: add integration section for systemd with dbus

[Yann E. MORIN]

Arnout, All,

On 2022-07-28 00:12 +0200, Arnout Vandecappelle (Essensium/Mind) spake thusly:
> Add a section to the "Integration topics" chapter about how we integrate
> systemd. Add a first subsection about how dbus and dbus-broker work with
> systemd.
> 
> This is just the start of the integration information about systemd.

Thanks!

> Signed-off-by: Arnout Vandecappelle (Essensium/Mind) <arnout@mind.be>

Applied to master, thanks.

Regards,
Yann E. MORIN.

> ---
>  docs/manual/integration-systemd.txt | 27 +++++++++++++++++++++++++++
>  docs/manual/integration.txt         |  2 ++
>  2 files changed, 29 insertions(+)
>  create mode 100644 docs/manual/integration-systemd.txt
> 
> diff --git a/docs/manual/integration-systemd.txt b/docs/manual/integration-systemd.txt
> new file mode 100644
> index 0000000000..44248b43ff
> --- /dev/null
> +++ b/docs/manual/integration-systemd.txt
> @@ -0,0 +1,27 @@
> +// -*- mode:doc; -*-
> +// vim: set syntax=asciidoc:
> +
> +[[integration-systemd]]
> +=== Systemd
> +
> +This chapter describes the decisions taken in Buildroot's integration of
> +systemd, and how various use cases can be implemented.
> +
> +==== DBus daemon
> +
> +Systemd requires a DBus daemon. There are two options for it: traditional dbus
> +(+BR2_PACKAGE_DBUS+) and bus1 dbus-broker (+BR2_PACKAGE_DBUS_BROKER+). At
> +least one of them must be chosen. If both are included in the configuration,
> +dbus-broker will be used as system bus, but the traditional dbus-daemon is
> +still installed as well and can be used as session bus. Also its tools (e.g.
> ++dbus-send+) can be used (systemd itself has +busctl+ as an alternative). In
> +addition, the traditional dbus package is the only one that provides +libdbus+,
> +which is used by many packages as dbus integration library.
> +
> +Both in the dbus and in the dbus-broker case, the daemon runs as user +dbus+.
> +The DBus configuration files are also identical for both.
> +
> +To make sure that only one of the two daemons is started as system bus, the
> +systemd activation files of the dbus package (+dbus.socket+ and the
> ++dbus.service+ symlink in +multi-user.target.wants+) are removed when
> +dbus-broker is selected.
> diff --git a/docs/manual/integration.txt b/docs/manual/integration.txt
> index bdfbfa59de..be56bf6567 100644
> --- a/docs/manual/integration.txt
> +++ b/docs/manual/integration.txt
> @@ -9,4 +9,6 @@ level. Buildroot is highly configurable, almost everything discussed
>  here can be changed or overridden by xref:rootfs-custom[rootfs overlay
>  or custom skeleton] configuration.
>  
> +include::integration-systemd.txt[]
> +
>  include::integration-selinux-support.txt[]
> -- 
> 2.35.3
> 

-- 
.-----------------.--------------------.------------------.--------------------.
|  Yann E. MORIN  | Real-Time Embedded | /"\ ASCII RIBBON | Erics' conspiracy: |
| +33 662 376 056 | Software  Designer | \ / CAMPAIGN     |  ___               |
| +33 561 099 427 `------------.-------:  X  AGAINST      |  \e/  There is no  |
| http://ymorin.is-a-geek.org/ | _/*\_ | / \ HTML MAIL    |   v   conspiracy.  |
'------------------------------^-------^------------------^--------------------'
_______________________________________________
buildroot mailing list
buildroot@buildroot.org
https://lists.buildroot.org/mailman/listinfo/buildroot

Re: [Buildroot] [PATCH 1/2] docs/manual: introduce "Integration topics" chapter

[Edgar Bonet]

Hello Arnout, hello all,

On 2022-07-28, Arnout Vandecappelle (Essensium/Mind) wrote:
> We want to add more information in the manual about how a system created
> with buildroot works overall. We currently already have a chapter about
> SELinux, but we want to add more information like that, e.g. details
> about how systemd in Buildroot works.
> 
> Create a new chapter "Integration topics" with an introductory blurb,
> and move the SELinux topic under it (as a section rather than a
> chapter).
> 
> "Integration topics" is not the best title, but we couldn't find
> anything better.
> 
> Signed-off-by: Arnout Vandecappelle (Essensium/Mind) <arnout@mind.be>
> ---
>  ...x-support.txt => integration-selinux-support.txt} |  6 +++---
>  docs/manual/integration.txt                          | 12 ++++++++++++
>  docs/manual/manual.txt                               |  2 ++
>  3 files changed, 17 insertions(+), 3 deletions(-)
>  rename docs/manual/{selinux-support.txt => integration-selinux-support.txt} (96%)
>  create mode 100644 docs/manual/integration.txt

[skip...]

> diff --git a/docs/manual/manual.txt b/docs/manual/manual.txt
> index b5cc044805..8ba0c76d32 100644
> --- a/docs/manual/manual.txt
> +++ b/docs/manual/manual.txt
> @@ -38,6 +38,8 @@ include::common-usage.txt[]
>  
>  include::customize.txt[]
>  
> +include::integration.txt[]
> +
>  include::selinux-support.txt[]

I believe the above line (selinux-support.txt) should be removed from
manual.txt.

Regards,

Edgar.
_______________________________________________
buildroot mailing list
buildroot@buildroot.org
https://lists.buildroot.org/mailman/listinfo/buildroot

Re: [Buildroot] [PATCH 1/2] docs/manual: introduce "Integration topics" chapter

[Yann E. MORIN]

Edgar, All,

On 2022-07-28 09:54 +0200, Edgar Bonet spake thusly:
> On 2022-07-28, Arnout Vandecappelle (Essensium/Mind) wrote:
[--SNIP--]
> > Create a new chapter "Integration topics" with an introductory blurb,
> > and move the SELinux topic under it (as a section rather than a
> > chapter).
[--SNIP--]
> > diff --git a/docs/manual/manual.txt b/docs/manual/manual.txt
> > index b5cc044805..8ba0c76d32 100644
> > --- a/docs/manual/manual.txt
> > +++ b/docs/manual/manual.txt
> > @@ -38,6 +38,8 @@ include::common-usage.txt[]
> >  
> >  include::customize.txt[]
> >  
> > +include::integration.txt[]
> > +
> >  include::selinux-support.txt[]
> I believe the above line (selinux-support.txt) should be removed from
> manual.txt.

Good catch, I've fixed that!

Regards,
Yann E. MORIN.

-- 
.-----------------.--------------------.------------------.--------------------.
|  Yann E. MORIN  | Real-Time Embedded | /"\ ASCII RIBBON | Erics' conspiracy: |
| +33 662 376 056 | Software  Designer | \ / CAMPAIGN     |  ___               |
| +33 561 099 427 `------------.-------:  X  AGAINST      |  \e/  There is no  |
| http://ymorin.is-a-geek.org/ | _/*\_ | / \ HTML MAIL    |   v   conspiracy.  |
'------------------------------^-------^------------------^--------------------'
_______________________________________________
buildroot mailing list
buildroot@buildroot.org
https://lists.buildroot.org/mailman/listinfo/buildroot

Re: [Buildroot] [PATCH 1/2] docs/manual: introduce "Integration topics" chapter

[Yann E. MORIN]

Arnout, All,

On 2022-07-28 00:12 +0200, Arnout Vandecappelle (Essensium/Mind) spake thusly:
> We want to add more information in the manual about how a system created
> with buildroot works overall. We currently already have a chapter about
> SELinux, but we want to add more information like that, e.g. details
> about how systemd in Buildroot works.
> 
> Create a new chapter "Integration topics" with an introductory blurb,
> and move the SELinux topic under it (as a section rather than a
> chapter).
> 
> "Integration topics" is not the best title, but we couldn't find
> anything better.
> 
> Signed-off-by: Arnout Vandecappelle (Essensium/Mind) <arnout@mind.be>

Applied to master with the fix spotted by Edgard, thanks.

Regards,
Yann E. MORIN.

> ---
>  ...x-support.txt => integration-selinux-support.txt} |  6 +++---
>  docs/manual/integration.txt                          | 12 ++++++++++++
>  docs/manual/manual.txt                               |  2 ++
>  3 files changed, 17 insertions(+), 3 deletions(-)
>  rename docs/manual/{selinux-support.txt => integration-selinux-support.txt} (96%)
>  create mode 100644 docs/manual/integration.txt
> 
> diff --git a/docs/manual/selinux-support.txt b/docs/manual/integration-selinux-support.txt
> similarity index 96%
> rename from docs/manual/selinux-support.txt
> rename to docs/manual/integration-selinux-support.txt
> index 21137ae6c3..1f6bcf47eb 100644
> --- a/docs/manual/selinux-support.txt
> +++ b/docs/manual/integration-selinux-support.txt
> @@ -2,7 +2,7 @@
>  // vim: set syntax=asciidoc:
>  
>  [[selinux]]
> -== Using SELinux in Buildroot
> +=== Using SELinux in Buildroot
>  
>  https://selinuxproject.org[SELinux] is a Linux kernel security module
>  enforcing access control policies. In addition to the traditional file
> @@ -30,7 +30,7 @@ upstream https://github.com/SELinuxProject/refpolicy[refpolicy]
>  project, enabled with +BR2_PACKAGE_REFPOLICY+.
>  
>  [[enabling-selinux]]
> -=== Enabling SELinux support
> +==== Enabling SELinux support
>  
>  To have proper support for +SELinux+ in a Buildroot generated system,
>  the following configuration options must be enabled:
> @@ -42,7 +42,7 @@ In addition, your filesystem image format must support extended
>  attributes.
>  
>  [[selinux-policy-tweaking]]
> -=== SELinux policy tweaking
> +==== SELinux policy tweaking
>  
>  The +SELinux refpolicy+ contains modules that can be enabled or
>  disabled when being built. Each module provide a number of +SELinux+
> diff --git a/docs/manual/integration.txt b/docs/manual/integration.txt
> new file mode 100644
> index 0000000000..bdfbfa59de
> --- /dev/null
> +++ b/docs/manual/integration.txt
> @@ -0,0 +1,12 @@
> +// -*- mode:doc; -*-
> +// vim: set syntax=asciidoc:
> +
> +[[integration]]
> +== Integration topics
> +
> +This chapter discusses how various things are integrated at system
> +level. Buildroot is highly configurable, almost everything discussed
> +here can be changed or overridden by xref:rootfs-custom[rootfs overlay
> +or custom skeleton] configuration.
> +
> +include::integration-selinux-support.txt[]
> diff --git a/docs/manual/manual.txt b/docs/manual/manual.txt
> index b5cc044805..8ba0c76d32 100644
> --- a/docs/manual/manual.txt
> +++ b/docs/manual/manual.txt
> @@ -38,6 +38,8 @@ include::common-usage.txt[]
>  
>  include::customize.txt[]
>  
> +include::integration.txt[]
> +
>  include::selinux-support.txt[]
>  
>  include::faq-troubleshooting.txt[]
> -- 
> 2.35.3
> 

-- 
.-----------------.--------------------.------------------.--------------------.
|  Yann E. MORIN  | Real-Time Embedded | /"\ ASCII RIBBON | Erics' conspiracy: |
| +33 662 376 056 | Software  Designer | \ / CAMPAIGN     |  ___               |
| +33 561 099 427 `------------.-------:  X  AGAINST      |  \e/  There is no  |
| http://ymorin.is-a-geek.org/ | _/*\_ | / \ HTML MAIL    |   v   conspiracy.  |
'------------------------------^-------^------------------^--------------------'
_______________________________________________
buildroot mailing list
buildroot@buildroot.org
https://lists.buildroot.org/mailman/listinfo/buildroot