clearlinux / clear-linux-documentation Goto Github PK

The :ref: at https://github.com/clearlinux/clear-linux-documentation/blame/master/source/clear-linux/concepts/swupd-about.rst#L126 causes the following sentence in the rendered web page:

Therefore, we provide a Use mixer tool.

https://clearlinux.org/documentation/clear-linux/concepts/swupd-about

It would be nice to have a document on the Clear Linux website that shows how to connect to a wireless AP as a client, using wpa_supplicant for example.

It could highlight and document the current state of network managers in CL and how they may change when using WiFi. (e.g. systemd-networkd vs. NetworkManager)

Should the new document be a guide, a reference, or a tutorial?
Guide.

Describe or provide examples of similar documents, if possible, from other web sites
https://wiki.archlinux.org/index.php/WPA_supplicant#Advanced_usage
https://shapeshed.com/linux-wifi/

Additional context
Both commandline and GUI examples would be useful.

https://clearlinux.org/documentation/clear-linux/reference/bundles is missing the description for dosfstools, even though there is a corresponding entry in https://github.com/clearlinux/clr-bundles/blob/master/packages (possibly because of a parenthesis that needs to be escaped?)

Hi, just wondering how sockets work...

When I push say a 10MB packet over a socket… does the process...

A) push the entire packet of data into the operating system, and then move onto other tasks?

or B) feed the 10MB incrementally to the operating system, as requested?

I'm trying to reason about the order in which operations will occur on contentious sockets all managed by the same process.

Environment (please complete the following):

• Clear Linux OS version: 27670
• https://clearlinux.org/documentation/clear-linux/tutorials/kubernetes as of 2019-02-08

Handling of the CNI directory is wrong in the current revision of the page.

CRI-O’s default plugin_dir is /opt/bin/cni. CNI plugins are installed as part of cloud-native-basic.

The actual path is /opt/cni/bin.

Notes about Weave Net add-on
...
Add the loopback CNI plugin to the plugin path with the command:

sudo ln -s /usr/libexec/cni/loopback /opt/bin/cni/loopback

/usr/lib/tmpfiles.d/cri-o.conf creates /opt/bin/cni, so the command above doesn't fail, but probably doesn't fix the issue (haven't tried).

Notes about flannel add-on
...
Create a symlink for the network overlays:

sudo ln -s /usr/libexec/cni /opt/cni/bin

This will fail once /usr/lib/tmpfiles.d/cri-o.confgets changed to create the directory.

Note

Clear Linux OS installs CNI plugins that are part of the cloud-native-basic bundle to /usr/libexec/cni. The directory is required because ` swupd verify` may use it to repair a system to a known good state.

That's correct, but it is not specific to flannel.

My proposal is to have one note that works for multiple CNI plugins and remove the workarounds from the flannel and weave sections:

Note

CRI-O’s default plugin_dir is /opt/cni/bin. This must be a writable directory, because third-party networking add-ons will install themselves there. CNI plugins provided by Clear Linux are installed as part of cloud-native-basic in /usr/libexec/cni/ and are currently *not* found by CRI-O by default. These separate directories are required because `swupd` controls the content of `/usr` and leaves `/opt` unchanged.

When using third-party network add-ons that rely on those plugins (like weave or flannel do), then make them available via symlinks:

sudo mkdir -p /opt/cni/bin
for i in /usr/libexec/cni/*; do sudo ln -sf $i /opt/bin/cni/; done

@mvincerx. Create a new tutorial on" creating a Clear Linux web based server" to support autospec and mixer guides. Current tutorial here does not support aforementioned guides:
https://clearlinux.org/documentation/clear-linux/tutorials/web-server-install#web-server-install

test: don't try to start kubelet before kubeadm

Starting kubelet before kubeadm isn't necessary and while it worked in
the past, it no longer does with Clear Linux 26630 / Kubernetes 1.12
(/var/lib/kubelet/config.yaml not found,
clearlinux/distribution#310).

Reference: intel/oim@b625d0a

This is a feature, not a bug. There are several places on the documentation that the user is asked to download a image from [1] and then unxz it. IMO, it would be great if the fetch step is also shown as a wget command including the full url of the most recent image, this way we make it easier for the user and avoid wrong image selection from user.

For example, on the kvm steps:

1. Download the latest pre-built Clear Linux KVM image file from the image directory. Look for clear--kvm.img.xz.

wget https://download.clearlinux.org/image/clear-19720-kvm.img.xz <-- this is the new piece of text that needs to be dynamically populated

[1] https://download.clearlinux.org/image/

If you strictly follow the instructions in the DLRS tutorial, the steps to clone and then run the TF benchmarks will fail. Need to add a first step to run the docker image:

docker run --name --rm -i -t <clearlinux/stacks-dlrs-TYPE> bash

[https://clearlinux.org/documentation/clear-linux/tutorials/dlrs](DLRS tutorial)

Describe the error/improvement to an existing document or image
currently, Clear Linux* sets a sshd.socket systemd unit that listens on the port 22 for SSH connections. However, it's not clear for the user the procedure to change the default ssh port.

Screenshots
N/A

Environment (please complete the following):

• Clear Linux OS version: 25430
• Third-party tool/software: N/A
• Command N/A

Additional context
Upstream SSH server provides the option of changing the default port by editing the /etc/ssh/sshd_config file, however, this is not compatible out of the box with the default sshd socket implementation of Clear Linux*, unless the sshd.socketis disables and the sshd.service is manually configured/enabled/started.

Describe the error/improvement to an existing document or image

https://github.com/clearlinux/clear-linux-documentation/blob/master/source/clear-linux/get-started/virtual-machine-install/kvm.rst - item 3 "On Clear Linux OS".

The swupd command line to install kvm-host includes desktop-start. I understand the idea behind that - make sure users have a graphical env in the CL host - however it should be explained in a separate (in many cases optional) step.

Additional context
I am following the doc steps to setup a vm, so my laziness made me simply copy & paste the swupd command line provide to install the kvm-host bundle. swupd informed I already have that bundle (goal achieved), but it continued to download content to install desktop-start (not part of my intent).

I tried installing clearlinux on a compatible laptop (or so did the compatibility tester .sh file say) and on VMware Player 14. In both cases I followed the guides on the clearlinux website, first the installation one and second the 'Create and enable a new user space' one. In both cases I arrived at the point where I would need to submit systemctl start gdm and, after putting my account's password and authorizing the thing, literally nothing would happen. Same thing trying with xinit or startx.

Description
It might be "system" rather than "sytem" in following link:
https://clearlinux.org/documentation/clear-linux/guides/maintenance/swupd-guide#example-3-verify-and-correct-sytem-file-mismatch

Screenshots

Environment

• Clear Linux OS version: clearlinux.org
• Third-party tool/software: None
• Command: None

Additional context
I found this error when I was visition clearlinux.org, and should i create issue for it in this repo?

Signed-off-by: Zhengtian Xie [email protected]

Both of these steps are highly discouraged by VMware:

• SSH into the ESXi host as root
• running vmkfstools on the ESXi host

We should rework the guide to perform the conversion elsewhere (if it's still necessary), and remove this section completely.

Currently, only 2 images are build to be used in a USB stick:

• clear-<VERSION>-installer.img
• clear-<VERSION>-live.img

However, the Create a bootable USB drive on Linux guide is a bit confusing about which images can be used on a USB stick by mentioning all Clear Linux* images available.

The proper guide should point out to create either an installer usb stick or a live usb stick using the clear-<VERSION>-installer.img or the clear-<VERSION>-live.img respectively, avoiding user to get confused with all image options Clear Linux* offers.

(Original report at clearlinux/distribution#85)

Two pages already exist to document the related topics of verifying image checksum signatures and image integrity:

• How to verify Clear Linux image integrity.
• How to validate the signature of a Clear Linux image checksum file. This section also covers image integrity verification, but a little differently.

It would be helpful for this documentation to be consolidated such that the steps are described in the same way.

Hi,

I am looking to install a fresh Hyper-V VM using ISO, IMG or anything which will allow me to have more control on how I want to set up Clear Linux. Just like the manual installation in Bare metal, but for Hyper-V.
I tried using the ISO to run the installation but failed (I used same VM settings used for the official Hyper-V VM: Generation 2, disable secured boot...)

Any help about how to install fresh Clear Linux on Hyper-V will be appreciated.

Notes:
1- I have successfully tried "Use Hyper-V" VM, It is working as expected, but would like to change the partitioning and add more space to disk.
2- I have successfully used "Increase Clear Linux image virtual disk size" as well.

Thanks,
Drissi

Review 4012.

Describe the error/improvement to an existing document or image
cloud-native-basic bundle does not install docker (through dependencies) anymore so extra steps is needed in the doc to have docker (containers-basic) installed.

Environment (please complete the following):

• Clear Linux OS version: [VERSION_ID=26410]

Reorg of the WordPress tutorial (PR #247 ) prompted a request for edits to the first part of the tutorial from @odwdinc.

Edits to the content of the tutorial will be done as a separate PR.

Requested changes:

1. Current content:
Open a text editor and perform the following:
Copy the content listed below into the new file /etc/httpd/conf.d/httpd.conf.
Question:
How do you open the text editor? as this is a procted file and you will need root the dir dus not excit
so you need to creat the dir befor you can add the file.
Suggestion/comment:

sudo mkdir -p /etc/httpd/conf.d
sudo nano /etc/httpd/conf.d/httpd.conf

2. Current content:
To ensure a successful setup, edit the new index.html file. Change the original text from
“This web server is operational from host.”
to
“This web server is operational from its new location.”
Suggestion/comment:
would be good to have the command agen to reinforce the need for sudo.
the dafualt text is worng as the it is "It works!"

sudo nano ./index.html 

3. Current content:
Create a file named phpinfo.php in the /var/www/html/ directory using a text editor.
Add the following line to the file:

<?PHP phpinfo() ?>

Suggestion/comment:
As this dir is oned by root you will need to creat and edit the file with sudo.

sudo nano /var/www/html/phpinfo.php 

4. Current content:
To check the status of MariaDB, enter the following command:
sudo systemctl status mariadb
Suggestion/comment:
no shown way to exit this status.
you will need to press 'ctrl+c' or 'q' to exit

5. Current content:
To add a basic layer of security, enter the following command:

mysql_secure_installation

Suggestion/comment:
fresh install is not have blank password, cant get passt

New pages will appear here: [https://clearlinux.org/documentation/clear-linux/guides]

1. Enter an 'x' in the category for the new "guide":

• [x ] Basics
• Developer
• Administrator

Complete the field below, following the colon, that matches option selected above:

I am a Clear Linux Beginner (Basics). I want to learn how to: Use the new issue template for Guides

I am a Clear Linux Developer. I want to learn how to:

I am a Clear Linux Administrator. I want to learn how to:

Revise regex to account for unintended capture of repeated data and sectional patterns.
#377

Assigned to @mvincerx

It looks like the build signing process and associated docs might have recently changed in clearlinux/distribution#85
and something trivial got missed.

As it stands today https://clearlinux.org/documentation/clear-linux/guides/maintenance/validate-signatures#image-content-validation appears incorrect. It states:

Important

The ./ in the file name must be included because it is part of the SHA512 sum of the image. Without it, the validation of the signature of the image will fail.

But if you look at for example https://download.clearlinux.org/image/clear-24750-vmware.vmdk.xz-SHA512SUMS the "./" is not in the file. Signature validation fails if "./" is included by the user when doing:

shasum -a 512 ./clear-24750-vmware.vmdk.xz > sha512sum.out

It appears the documentation should have the suggested command as:

sha512sum clear-$(curl https://download.clearlinux.org/latest)-installer.img.xz > sha512sum.out

and a note like:

Important

Path information such as "./" or "/home/myuser/Downloads/" MUST NOT be included in this command line for the image file, because it becomes part of the SHA512 sum of the image. Without an exact filename match versus the downloaded SHA512SUMS contents, the validation of the signature of the image will fail.

Testing with 24750 images, none of the SHA512SUMS files have a "./" inside them.

Describe the error/improvement to an existing document or image

In the guide to run Clear Linux as a KVM guest OS, section "Download and launch the virtual machine":

• Step 3 tells users to download the OVMF file (side note: there could be a copy&paste friendly curl line to download it);
• Step 4 tells user to do a cp of the same file from /usr/share/qemu.

These steps seem to conflict (imagine if the user downloads the file to workdir, then follow step 4... one file would overwrite the other).

Considering the recommendation in the "Note" after those steps, it seems steps 3 and 4 target different users: step 3 non-CL hosts, step 4 CL hosts.

Still, I downloaded OVMF from the link provided then compared (md5sum) that file with the one at /usr/share/qemu in my Clear Linux host, and they are different... So that made me think: Which version is the best to use?

Environment (please complete the following):

• Clear Linux OS version: 28230

CLR main page [1] shows more 1.6k contributors (1688). This is too much and the number needs to be double check.

[1] https://clearlinux.org/

In the recent mixer documentation rewrite (#80), the various steps were broken out into separate sections. A Current mixing workflow section was added to the top, with links to the various other sections below. These hyperlinks do not currently work, and instead all point back to the main document itself.

It's not clear to me why these hyperlinks are not being generated properly. In theory, they should work, and they look correct to me. According to the reST spec, all section titles are automatically used as "implicit hyperlink targets". The hyperlink references look correct to me -- they simply need to match the title text exactly, and they do.

We're using Sphinx to build our reST pages. The Sphinx documentation advises against using implicit hyperlink targets like this, but only because they do not work across documents the way their :ref: extension does. Within a document, they are supposed to work fine.

One potential workaround would be to add "explicit hyperlink targets" and update the hyperlink references to point to them. That could be taken a step further to use full-fledged explicit :ref: targets, but then they would need to be unique across the entire document set. I have not tested either approach. If both work, I would recommend the first over the latter for simplicity.

Describe the error/improvement to an existing document or image
We have introduced DKMS support for out-of-tree kernel module building. We should add instructions for installing the bundle, using the dkms tool to build and install out-of-tree modules, and how to update them. We should also mention that installing the bundle disables module signature verification, show the message it adds to the MOTD, and explain how to disable that feature, if necessary.

Additional context
Probably should add content here.

Basics on using DKMS

User will need to bundle-add kernel-native-dkms, which:

• provides the dkms tool
• provides (via include) the very large linux-dev bundle, which includes the files necessary to build out-of-tree modules against the native kernel.
• adds an update trigger /usr/lib/systemd/system/dkms-new-kernel.service to automatically run dkms to rebuild modules after a kernel upgrade
• adds (via /usr/share/kernel/cmdline.d/clr-ignore-mod-sig.conf) a kernel command-line argument, module.sig_unenforce, that disables kernel module signature verification, allowing out-of-tree modules to be loaded.
  • This has security implications
  • This can be disabled via /etc/kernel/cmdline-removal.d/*.conf (see clr-boot-manager manpage), but will result in not being able to load dkms-built modules.

After installing the bundle for the first time, the user will have to run sudo clr-boot-manager update manually to apply the kernel command line change. This is called from swupd when a new kernel is installed, but not merely by installing this bundle.

Describe the error/improvement to an existing document or image
I have set up a Virtualbox instance using Vagrant to try the tutorial on getting up and running with k8s on the clearlinux.org site.

• The Vagrantfile is located here: https://github.com/shrmrf/k8s-resources/blob/master/clear/Vagrantfile
  • This file tries to follow the tutorial until the actual run command
• The run log is here: https://github.com/shrmrf/k8s-resources/tree/master/clear#problems
  • I get the same error when I run something like sudo -E kubeadm init --pod-network-cidr 10.244.0.0/16 --ignore-preflight-errors=SystemVerification

Screenshots
NA

Environment (please complete the following):

• Clear Linux OS version: 25360
• Third-party tool/software: [docker version 18.06, kubeadm version 1.11]
• Command [kubeadm init]

Additional context

• I am using the Vagrant box AntonioMeireles/ClearLinux-packer with Virtualbox.
• The problem could lie with the box as well, though unlikely IMO.

From distribution created by shrmrf : clearlinux/distribution#215

Is your feature request related to a problem? Please describe.
Documentation which describes (tutorial style perhaps) modification of the Linux kernel, adding and signing kernel modules is missing.

Describe the solution you'd like

• Tutorial on how with best-practices for Linux Kernel modification
• Kernel module signing documentation etc.
• Compiling a kernel module to run against Clear Linux

Describe alternatives you've considered
NA

Additional context
NA

The documentation on mixer requires major update since we have upgraded mixer to v5.x.
The steps still showing the old command: e.g. build chroots and it is not valid now.

Describe the error/improvement to an existing document or image
The current multiboot install instructions suggest disabling grub and modifying the menus in clr-boot-manager to boot other distributions using grub like Ubuntu. However it's simpler to simply add a single menu item to let the clr-boot-manager to invoke grub if selected. This also lets the target OS update its kernels, options etc. without having to change the configuration files for clr-boot-manager. It also makes the configuration files for clr-boot-manager simpler since you don't have to copy over all the options, etc. This does not even significantly slow down autonomous boot if you give both of them short timeouts (I use 5s for both).

For example, in my system, where I dual-boot an ubuntu installation in this way, I added only the following in /boot/loader/entries/ubuntu.conf:

title Ubuntu
efi /EFI/ubuntu/grubx64.efi

And now I never have to touch this again.

Screenshots
If applicable, add screenshots to help explain the error or unexpected behavior.

Environment (please complete the following):
NAME="Clear Linux OS"
VERSION_ID=26170

Additional context
There is a related issue with swupd that clears the timeout on the boot manager when you do an update. There is an easy fix but I thought I would mention it here since it will affect people who are doing multiboot so maybe the workaround should also be documented in the same place:
clearlinux/swupd-client#683

Describe the error/improvement to an existing document or image
Autospec does not require a mix already deployed. I think this is an error in the prerequisite section of the autopsic document: https://clearlinux.org/documentation/clear-linux/guides/maintenance/autospec

"Prerequisites
This guide assumes that you have:
Created a custom mix of Clear Linux OS and deployed it to a to a target device
Clear Linux OS running on a host machine or virtual environment"

Can we remove the line: "Created a custom mix of Clear Linux OS and deployed it to a to a target device"?

Following document: https://clearlinux.org/documentation/clear-linux/concepts/swupd-about

Has odd arguments about package management "issues" with other distributions (i.e. what advantages swupd / bundles would have compared to them):

• "This can be done effectively, but given the nearly endless combinations of packages and versions of packages a server may have, it quickly becomes non-trivial to define what “version” the system is and what software it is running without explicitly going through each system and inspecting every package."

• "This matters on a daily basis to system administrators, who need to determine which of their systems do not have the latest security fixes, or which combinations of software have been tested."

For example, on Debian / Ubuntu:

• Checking whether available security updates have been installed, can be seen with "apt update" command (which is shorter command than "swupd check-update")

• If maintainer just wants everything to have the latest security updates, s/he just enables automatic security updates

• If s/he wants more control, machines s/he maintains get packages from a mirror / proxy in her/his control (which is updated from upstream only after testing, or where packages are "hand-picked")

So basically the "advantages" boil into swupd providing a single number for identifying the distribution package content. However, that's not really useful as it doesn't tell anything.

As far as I can see, there's no way in ClearLinux to find out relevant things corresponding to its distro version:

• Does it have version of Y (or newer) of package B, which got the feature my app would need?
• Does it include version X of package A with a known security vulnerability?
• Does it have patch applied that fixes the issue?

E.g. in Debian/Ubuntu:

• "dpkg -s " shows the package upstream version
• "apt source " fetches package sources for more in-depth examination
• there's also a www-site where one can check which package versions are in which distro versions, their changelogs, included files, applied changes and a list of package specific bugs:
  ** https://packages.ubuntu.com/
  ** https://packages.debian.org/

Describe the error/improvement to an existing document or image
Improvement
Revise descriptions on these pages for brevity:

https://clearlinux.org/documentation/clear-linux/guides
https://clearlinux.org/documentation/clear-linux/tutorials

Or, remove first sentence with 3-bullet description.

Additional context
Add any other context about the problem here.

Do you think Clear Linux documentation needs a new document? Please describe.

For someone who’s new to K8S, should there be a Kubernetes Tutorial Part II? Should we show how to?:

• Add an overlay network
• Join two nodes
• Deploy a containerized application

Refer to discussion btw: @bktan8 , @joselamego , and @mvincerx.

Should the new document be a guide, a reference, or a tutorial?
Recommend a type of document, based on the structure here:

Tutorial

Describe or provide examples of similar documents, if possible, from other web sites
See current k8s tutorial: https://clearlinux.org/documentation/clear-linux/tutorials/kubernetes

#255

URL https://clearlinux.org/documentation/clear-linux/get-started/bare-metal-install#bare-metal-install

Curl example gives a 404...

curl -O https://download.clearlinux.org/image/clear-$(curl https://download.clearlinux.org/latest)-installer.img.xz

Are *.gif files allowed for tutorial pages on clearlinux site?

I would like to record a small gif for showing up some steps instead of just plain *.png images, but if *.gif files are not allowed/supported, I could use the images as well.

#142

TBD: After performance concerns are resolved btw DPDK and CL, resume use of this document, per conversation with @nesiusra.

When trying to run install-vbox-lga, it asks for gcc, perl and linux headers.

The Dev bundle solves gcc and perl.

But I can't sort out how to install the linux headers. I've downloaded the source for the LTS release of the kernel. I've installed the linux bundles.

I'm totally stumped. Any help would be appreciated.

Thanks!

starting from installer version 22600, Clear Linux* now supports full disk encryption, but current documentation does not provide details about this new use case.

Plase add this new install case into the proper documentation page for installing clearlinux.

I'm adding the screenshots of the install for using disk encryption.

Please notice the following screen lists the new feature as a check-box to encrypt the root partition

Describe the error/improvement to an existing document or image
https://clearlinux.org/documentation/clear-linux/get-started/virtual-machine-install/kvm

For the above document, the preferred approach for a Clear Linux host to use OVMF.fd is to copy it from /usr/share/qemu/OVMF.fd to the working directory. For non-Clear Linux hosts, the preferred approach is to download it from https://cdn.download.clearlinux.org/image/OVMF.fd.

Screenshots
N/A

Environment (please complete the following):

• Clear Linux OS version: Any version
• Third-party tool/software: N/A
• Command: N/A

Additional context
This should be done to help address the version fragmentation we're experiencing with this file, as mentioned in a distribution issue.

Add link to increase the disk size in the Next Steps section of Getting Started/Install Clear Linux OS in a virtual machine. The link is: https://clearlinux.org/documentation/clear-linux/guides/maintenance/increase-virtual-disk-size

The available bundles file (https://github.com/clearlinux/clear-linux-documentation/blob/master/source/clear-linux/reference/bundles/bundles.html) is very out of date. Last updated October of 2017. We have added dozens of new bundles since then, including many pundles. Many of the includes have changed as well.

The effected external page is https://clearlinux.org/documentation/clear-linux/reference/bundles/available-bundles

It would probably not be difficult to write a script to generate this list instead of having to manually update it.

In the "Finish installation" section, the last step to set up root account is missing.

Need to add this step back in (instructions and screenshot is available in git history https://github.com/clearlinux/clear-linux-documentation/tree/c21f3b93013cc72ea550db5ec41c8268a0cfd66d , from Nov 2018)

https://clearlinux.org/documentation/clear-linux/get-started/virtual-machine-install/virtualbox#virtualbox

curl -O https://download.clearlinux.org/image/$(curl https://download.clearlinux.org/image/latest-images | grep live)

needs to be changed to:

curl -O https://download.clearlinux.org/image/$(curl https://download.clearlinux.org/image/latest-images | grep 'live\.')

due to:

$ curl -s https://download.clearlinux.org/image/latest-images |  grep live
clear-27870-live-desktop-beta.img.xz
clear-27870-live.img.xz

Maybe other places in the documentation too, I did not check ...

The stacks main page has a duplicate picture. We should replace the duplicate with the 'multi-node' image.

Describe the error/improvement to an existing document or image

The new document https://clearlinux.org/documentation/clear-linux/tutorials/greengrass has an error in adding the bundles:

swupd bundle-add os-clr-on-clear desktop-autostart computer-vision-basic

Should be

swupd bundle-add os-clr-on-clr desktop-autostart computer-vision-basic

Re doc: https://clearlinux.org/documentation/clear-linux/tutorials/kubernetes

Pending response from: clearlinux/distribution#239