There once was a nice set of openSUSE user manuals in PDF form covering pretty everything, — the main document had near 30 chapters in more than 500 pages, and there were also separate documents focusing on more specific topics. At least I still see something like that for openSUSE 11.0 on Novell site and from 11.3 to 12.2 on doc.opensuse.org, but had no luck finding similar thing for current releases.
In YaST package manager there is patterns-openSUSE-books
item in Documentation section, but it provides no real content.
Surprisingly, doc.opensuse.org
's front page also suggests the ActiveDoc site — not only in the page preface, but in each and every particular link regarding openSUSE 13.1 documentation, — thus creating an infinite loop.
Trying to access the mentioned URIs from doc.opensuse.org
itself gives nothing but a 404 Not Found error.
So, am I missing something obvious? Where that openSUSE Reference can be found now?
Starting with openSUSE 12.3 we moved the documentation to activedoc.opensuse.org, in a move to allow the community to easily contrbute to the manuals. However, we did not get as much contributions as we expected. Therefore two weeks ago the SUSE documentation team decided to take care of the openSUSE ocumentation again. Since then, openSUSE Leap 42.1 documentation is available on http://doc.opensuse.org/ (and we will publish updated documentation for upcoming Leap releases there, too).
–
Frank Sundermeyer
SUSE Documentation Project Manager
“Reality is always controlled by the people who are most insane” Dogbert
Hmmmm…
I’ve looked over the Virtualization “Books” because it’s something I know pretty well and IMO it’s only suitable for someone’s early baby steps when they are just getting started.
The Virtualization content is rife with half-truths and definitions on every page and on some pages although won’t get a beginner in trouble immediately are very, very wrong about architecture and definitions so is putting a lot of wrong information into the reader which stunts further learning.
At least regarding virtualization, for now I’d recommend a User simply search the posts in the Virtualization forum for how to do things, and there are questions about how things work, are architected or choices, just ask in that Forum.
In my not so humble opinion, documents of such quality should better be written by as few people as possible, — ideally by a single person per knowledge domain. Wiki-style of editing is more suited for isolated articles, FAQs and how-tos, not for books. So your recent decision was entirely right, thank you so much — that is exactly that I was looking for.
While I cannot judge on current content’s truthfulness and completeness (my own fear is that it may not be up-to-date, especially regarding Xen), but I am very confident that such form of documentation is the very best for beginners — not only explaining basics in a highly systematic way, but also teaching how to do things in ${distroname} way. In contrast, learning from forum posts and “repeat after me” how-tos tends to be shallow and confusing, making to get accustomed to bad practices. That is why books are so important, and if you see errors there, please, inform the authors so they could improve the text, or even volunteer to become an author yourself.
As an absolutely non-humble software tester, my view is that because “human beings produce errors” (only robots can produce error-free products) all text (including program code) must be reviewed and inspected and (ideally) tested and written by a group of people who have subject insight . . .
Considering the issues of consistent style and uniform appearance, simply allowing one single human being to write text blocks does not automatically guarantee consistent style and uniform appearance; the human brain ensures that we all tend to deviate during writing and therefore each individual human being tends to produce inconsistent text styles and non-uniform appearance.Yes, yes, strict text-frame based text production tools can help to guide authors to produce text with a consistent style and a uniform appearance but, expect an initial resistance from the authors when they are first confronted with these tools . . .
Yes, yes, but, in an open-source world the Wiki method is extremely useful for conducting reviews of submitted text and for gathering the material needed for the production of more “formal” documentation . . .
Agreed; good documentation is needed at all levels of any given product:
short, concise and precise guides for the “1st contact” case;
moderately detailed documentation for change planning and testing;
detailed documentation for the system architects, designers and developers.
Yes, yes, I know: “Code is fact, documentation is fiction!”
After having examined a number of other Guides,
Most of what I read looks pretty good.
Some stuff I knew, plenty of stuff I didn’t and generally all easily understood.
Here’s hoping that the Virtualization guide is brought up to the level of the others, as I described earlier although I don’t see specific described methods and steps that are so inaccurate so as to cause harm, a very large (even majority) of the content is very weak on technological concepts, so much that if a reader relies on the information there would be plenty of un-learning to do and might not be able to progress beyond simple introduction to setting up.
Being one of the three authors of the Virtualization Guide I think this general statement is neither true nor fair (especially in the light of what you say below, see my comments on that). Sure, the guide is probably not perfect, nor error-free. But saying it is “rife with half-truths and definitions on every page” without giving any proof of it is not helpful at all.
Feedback (and that includes negative one) is always welcome, but if it does not include the slightest hint on what needs to be changed, there is little we can do with it. If we receive constructive criticism we may not react immediately, but you can be sure that it is not forgotten and will be considered in future editions of our manuals.
At this point I need to mention that TSU2 offered help in a private comment, which is much appreciated!
Funny thing is, that the Virtualization Guide is the result of a merge of these three guides. Since all can be managed using libvirt and tools we decided to merge these separate guides into a single virtualization guide. The KVM and libvirt part (the former SUSE KVM manual) remained almost unchanged (apart from significant additions to the libvirt chapter “Configuring VMs”), parts of the XEN and LXC guide have been changed to fit the new structure.
After thinking about your documentation more,
I’m beginning to believe that the actual problem isn’t that most of the written information is incorrect (It still is), but that it’s because the Author(s) are likely Xen users and don’t really use other virtualization that much.
Xen is a completely different beast, in its own category (often referred to as Gen1 virtualization which is <not> less capable than Gen2 which is the rest of all virtualization including KVM, VMware, VBox, Hyper-V, Parallels and more). Besides its own unique foundation architecture, for whatever reason Xen uses same terminology as everyone else to describe completely different things. So, if you intend to apply your Xen definitions and understanding to anything outside of Xen… Well, good luck. You won’t go too far before things will become very wrong when you discuss with and about other virtualization.
I admit that I personally view Xen more as something interesting from afar, because I haven’t found a need to deeply use it, but I use many others including KVM, VMware, VBox and Hyper-V and so I live in a world that all the virtualization I use do speak more or less the same language and are built and define things similarly.
That said,
The following is a short list (not intended to be complete) on where existing documentation is wrong, and since the list is long did not post before. For the Xen user, these errors might not be recognized but the errors I describe do not describe Xen specifically, they are supposed to describe other virtualization or virtualization in general (most of the world).
1.4 Full Virtualization is not described accurately, and actually has little to do with underlying hardware assist which is often disabled or not used which <enables> full emulation of non-x86 architectures when running on an x86 CPU. By its very name “paravirtualization” means that virtualization is based on, and is direct access to the CPU. Yes, Xen defines everything differently. “Full Emulation” for the rest of the world is basically non-hardware software emulation but somehow Xen seems to want to say that theirs is hardware based and Xen defines paravirtualization as not using CPU extensions. Xen wants to walk its own walk, but it’s not the “world definition”
1.5 I/O virtualization is generally considered separate from the CPU and was created to make this distinction during the evolution of virtualization which was historically Gen1 (CPU and memory only), Gen2 (CPU and memory, plus device I/O), more or less. there is plenty of disagreement exactly where the distinctions and generations are defined and some will define Gen2.5 to further distinguish between different types of I/O devices and now, moving forward even a Gen3. These evolutionary “Gen” labels are different than the “Gen” labels mentioned above that differentiate Xen from the rest of the world.
3.1 Saying KVM is a “full virtualization solution” is not accurate if you define full virtualization as full emulation. By default, KVM is implemented as paravirtualization, and only optionally can implement full emulation(virtualization) since the integration of QEMU. If you might mean that a “full solution” means that KVM supports a multitude of scenarios generally, then this word choice is confusing.
4.0 Saying that Linux Containers in any way virtualizes anything including the kernel has to be technically false, assuming the common definition of virtualization. Container processes aren’t run as virtualized representations of something else, they are no different than any other running process. Linux Containers are isolation, pure and simple with <no> virtualization <except> in <some> implementations networking objects (LXC but AFAIK no other Linux Containers implementation including docker and systemd-nspawn). Also, it should be noted that this documentation only defines “Linux Containers” as LXC and ignores all other implementations of linux containers.
4.1 I think you can remove the “nearly” word when describing performance.
controlling network interfaces through cgroups? I’d have to check up on that… That’s a bold statement I haven’t seen before, so I find suspicious. Depending on what you mean by security, using cgroups and process labels are significant security measures, I don’t know if non-security folk can distinguish or understand properly what was stated here.
5.0 In general, nothing wrong in the section. But, does not describe the scope of what libvirt can do, it can be used to manage at least a dozen or so different virtualization technologies, not just the three mentioned. Yes, SUSE/openSUSE only implements the three. If you install OpenStack on SUSE/openSUSE, you’ll also be using libvirt to support docker. BTW - considering how important docker has become to Linux and computing in general (it’s one of the top 3 topics for 3 years running at the Linux conferences I go to), it’s likely a serious omission if you’re describing Linux Containers. For now, unless you’re running OpenStack, openSUSE is providing a separate, non-libvirt management tool.
7.1 Why should paravirtualization support be any different for any Linux Guest distros? For that matter, why should Windows not be supported by paravirtualization, since the Windows kernel will have direct access to the CPU? Plenty of questionable things, this whole table should be re-written or thrown out, it’s based either on outdated info or has been mis-interpreted in its new incarnation. Or, again this section might have been written “The World according to Xen” which would become erroneous when applied to other virtualization.
7.1.1 As I alluded before, I highly recommend using the term “device drivers” instead of just “drivers” to be more exact, otherwise the info is only half correct. This is because this applies only to getting data in and out of the virtual machine and does not apply to any other types of drivers.
7.3 How about that. Description is accurate although I don’t know if the author really understood the accuracy of what was written. Should use the word “paravirtualization” to neatly tie up the relationship of hardware CPU extensions and what paravirtualization is to make this fully clear.
7.4 Needs to make clear this section applies <only> to Xen which is a completely different architecture than any other (often referred to in its own way as Gen1 virtualization). Every other paravirtualization technology I know of uses the “other” fundamental architecture (often referred to as Gen2) (The Gen number is not necessarily an indication Gen2 is any more advanced, it’s just different). Besides not specifying Xen in the title of this section, at least the HTML docs place this on the same page as the previous KVM documentation.
13.0 I don’t think there is understanding of the Linux Bridge Device and its relationship with virtual networks. The documentation seems to simply assume that a virtual network will magically work with only its XML file definition, but that’s not true. The reader should be introduced to the Linux Bridge Device (possibly with existing, maybe expanded description of brctl) and that it is the fundamental device upon which <all> network connections of all types are made, not just the physically bridging configuration described.
I’m sure that there is more that has to be evaluated, but that is as much as I can skim over for now… Again, I’m pretty certain that everything I’ve described can be more accurately found in the other references I provided earlier
A tiny update to my previous post when I mentioned how surprising to me that network interfaces would be controlled by cgroups…
Unless a new reference can be found, the web search hits I’m getting that I consider authoritative are describing network interfaces as controlled by namespaces and should be included in the cgroup of the container.
This is totally logical, and is not the same as setting up some cgroup specifically for a network interface(s).
I may still be surprised with a new reference somewhere…
TSU
Boy, these errors and omissions keep dribbling through my mind even after my previous skim this AM…
Another what I consider significant error/omission is that the existing documentation leads the reader to believe that libvirt is a must-use with KVM and suggests that virsh is the only way to manage KVM from the command line.
Of course, it’s also possible to use the “kvm” commands if the User wishes, and might be a significant option if libvirt somehow wasn’t functional.
Again, IIRC this is all available in the SLES KVM documentation I referenced…
For those who might come across this post which I consider a personal watershed in that it is the first and generally only detailed criticism I’ve posted about openSUSE virtualization documentation, technology has evolved slightly and the openSUSE documentation has as well (but not much).
Two years after this post,
I would suggest the following changes have happened…
The SUSE documentation as adopted and integrated the inaccuracies I pointed out in openSUSE virtualization, so I will not currently recommend any SUSE 12.x documentation for beginners, instead “freezing” my recommendation on SLES 11 SP4 for beginners. Once the User has a well established foundation understanding virtualization, I do encourage the User <then> to explore the SUSE 12 virtualization documentation which contain valuable nuggets of information, some which are not described in other references. Since almost all of the criticisms in post #8 have gone unaddressed, I assume that a silent decision was made that I was and am severely mistaken or that what I consider important is not.
Referencing the above post #8
1.4 Today, Full Emulation for both KVM and Xen Paravirtualization (both describe nearly the same thing) enjoy some hardware assist, but not to the extent that the “other” mode utilizes CPU virtualization extensions. This generally means that there is not nearly the same lagging performance penalty that existed in the past.
5.0 Although openSUSE documentation for Docker and default options to manage Docker have not changed significantly, an SDB:Docker page has been created with links to some good generic info on the Docker site
For those who are brand new to Docker, I still consider the pages I created modifying official docs at the time to use openSUSE tools a good reference. The basic commands and procedures of the time still apply today, but does not include info on important additional tools which were developed later (like Compose) and current areas of extreme interest like Kubernetes (SUSE is developing its own flavor called CAASP).
Was a bug report ever raised for a documentation update request? Don’t think the authors are necessarily paying attention here. (I’ve submitted a couple of such reports in recent times to attract the attention of those who are responsible for maintaining documentation.)
At the time, documentation requested that comments about the documentation be sent by a special email link, which was where a partial list (IIRC about half of the items in this thread) was sent. There was a short exchange of emails, but no commitments to review or edit the published documentation. IIRC a couple weeks after the last exchange of emails, this thread was posted.
So no, there wasn’t an issue submitted through bugzilla but was because by request by the documentation project.
From the first day I have only been interested in correcting these issues and because there hasn’t been any resolution either by correcting or by saying that I’m wrong, I can only post when appropriate that <beginners> should not use current virtualization documentation to learn. When the User has a solid foundation, I still advise that there is good information to be found so virtualization documentation should not be ignored altogether.
Also,
The only reason why I posted this list of issues publicly is because I was challenged in the previous post for not posting details. Until then, I had submitted any list privately.
Maybe.
At the time I balked at doing the actual work myself because there were too many problems which would have required essentially re-writing the whole thing.
I figured if people knew there was a problem then either existing SUSE employees would know what to do themselves or would know someone already on payroll to bring in.
Am still reluctant at volunteering what would amount to full time work since last time I checked the problem had more than doubled when the same problems began appearing in the SLES 12 documentation.
I guess first step will be to find a DocBook editor I’d be comfortable with…
Then do a new review of content.
