Feedback on (mostly) documentation

Bas
Beiträge: 4
Registriert: 02 Mai 2018, 10:25

Feedback on (mostly) documentation

Beitragvon Bas » 02 Mai 2018, 11:09

Recently I used and installed opsi for the first time.

First off, I was very impressed on the server as well as docu. Unfortunately, there as some errors in it, as described below;
  • In my experience, Java 7 wasn't able to run the configed, but Java 8 was - unlike it was stated in the guide (p. 14).
  • In the requirements it isn't super clear whether a DNS server is necessary (it is not).
  • If dialogues doesn't pop up during server installation, dpkg-reconfigure might help (p. 13), esp. aftpd. I am not sure how necessary this is, or if the configuration simply happens at a later time else.
  • p13 samba & pcpatch: Are there some warnings (for instance, about missing modules) etc. mentioned to early in the guide? It seemed these are relevant only later in the installation process (such as p. 27). Leaving meaningless warnings (for that time) too early in the docu might create some confusion, as it did to me.
  • Same might be said about describing the backend config @ p26/27.
  • PXE booting: Consider stating that the error "SIOCDELRT: No such process" doesn't affect functionality.
  • There are people (like me) who aren't very experienced with DHCP. Please state whether IP or MAC/both are necessary for entries @ configed if booting via PXE or for which other options
  • It would be more helpful and comfortable for orientation to have the chapter/subchapter and page number shown at the page header so it is more clear to the reader at which position on the document he is right now.
  • Didn't re-check yet, but the script create_driver_links.py is mentionend in the guide, but I think I couldn't find out where it is located nor was it described there.
  • The guide in the docu regarding opsi-scripts and how to install new opsi-products is too detailed. It was, to say the least, overwhelming to read when you just want to create a simple opsi package. I think it might be beneficial to reduce it to something like this simple Firefox setup code:
    wiki/doku.php?id=userspace:firefox
  • Creating WinPE by opsi doesn't seem to work for Win 7, only for 8 and above. The document doesn't really state this, so I had to figure it out for quite some time and was left outin the dark.
  • Maybe describe how the SSL cert should look like (opsiconf SSL cert), for instance, what a common name etc. is
The feedback is based mostly on PDF docu 4.0.7 EN:
http://download.uib.de/opsi_stable/doc/ ... ble-en.pdf

Outside of docu:
  • With the pxe boot image I used, I only had ONE (!) second to select a device before it went it autoboot mode and booted from HDD (after opsi boot image was found). Prob was the x86 boot image, can check if it helps.
  • When installing the opsi client, I had the issue that there was some window popping up (or not) in which the user is asked about some authentification information. Unfortunately, for me the window didn't seem to appear on the fore-, but rather the background - with no task bar entry either. There was no clear indication that there is some input required if there is nothing to see for the user. I suggest to at minimum create a task bar entry for that window. To find out about this did cost me roughly eight working hours. For the time being, it might prove helpful as a workaround to include a hint in the documentation.
  • This was in a VM in virtualBox, so it might be related to that, but I think whenever the fields from the opsi boot image were auto filled via DHCP (screen with blue background) the input stopped working and I had to reboot until they weren't automatically filled out.

Hopefully this proves as a vulnerable and helpful feedback to you!

Benutzeravatar
n.wenselowski
Beiträge: 2898
Registriert: 04 Apr 2013, 12:15

Re: Feedback on (mostly) documentation

Beitragvon n.wenselowski » 09 Mai 2018, 13:42

Hello Bas,

thanks for your feedback!
As for the documentation I tried to improve most of the things you mentioned and they should be available with the next documentation build so everyone can benefit.

Bas hat geschrieben:If dialogues doesn't pop up during server installation, dpkg-reconfigure might help (p. 13), esp. aftpd. I am not sure how necessary this is, or if the configuration simply happens at a later time else.

These dialogues are optional and you usually will be able to reconfigure these parts later on through configuration files.

Bas hat geschrieben:p13 samba & pcpatch: Are there some warnings (for instance, about missing modules) etc. mentioned to early in the guide? It seemed these are relevant only later in the installation process (such as p. 27). Leaving meaningless warnings (for that time) too early in the docu might create some confusion, as it did to me.

The behaviour of opsi has changed and we since recently don't show prominent warnings if the modules file is missing. I removed this to avoid confusion.

Bas hat geschrieben:PXE booting: Consider stating that the error "SIOCDELRT: No such process" doesn't affect functionality.

When did this message appear to you?

Bas hat geschrieben:The guide in the docu regarding opsi-scripts and how to install new opsi-products is too detailed. It was, to say the least, overwhelming to read when you just want to create a simple opsi package. I think it might be beneficial to reduce it to something like this simple Firefox setup code:
wiki/doku.php?id=userspace:firefox

I disagree in this case. Having someone to just copy a script without understanding why the things in the script are the way the are and where to place what part of an opsi package educates people so they can later on create their own scripts.
But you have a point in the guide being maybe a tad too extensive in some places. I'll see what can be done in this case to not overwhelm new readers.

Bas hat geschrieben:Creating WinPE by opsi doesn't seem to work for Win 7, only for 8 and above. The document doesn't really state this, so I had to figure it out for quite some time and was left outin the dark.

Could you elaborate a little bit on what you tried and what didn't work for you? The procedure is the same since Windows Vista and we've usually update the guide to work with the latest versions.

Bas hat geschrieben:Maybe describe how the SSL cert should look like (opsiconf SSL cert), for instance, what a common name etc. is

I feel that this is somehow outside of the scope of the getting started. But on a properly configured server you can just OK all of the questions and continue. Would you think that this would be a helpful hint?

Bas hat geschrieben:With the pxe boot image I used, I only had ONE (!) second to select a device before it went it autoboot mode and booted from HDD (after opsi boot image was found). Prob was the x86 boot image, can check if it helps.

This behaviour is intentianol. It is usually expected that if you want to i.e. install a netboot product on a client you set this product to setup in opsi and then you won't have to manually select that the bootimage should be booted.
If you think a larger timeout would help you can alter the file /tftpboot/linux/pxelinux.cfg/default.menu and change the timeout to something larger.

Bas hat geschrieben:When installing the opsi client, I had the issue that there was some window popping up (or not) in which the user is asked about some authentification information. Unfortunately, for me the window didn't seem to appear on the fore-, but rather the background - with no task bar entry either. There was no clear indication that there is some input required if there is nothing to see for the user. I suggest to at minimum create a task bar entry for that window. To find out about this did cost me roughly eight working hours. For the time being, it might prove helpful as a workaround to include a hint in the documentation.

I couldn't reproduce the behaviour that the window appears in the background. What OS did your client have? Does it have any settings aside from the Windows defaults that may change the behaviour?
I'll check what can be done to make it more prominent that input is required!

Another possibility is to use silent_setup.cmd but this requires some preparation.

Bas hat geschrieben:This was in a VM in virtualBox, so it might be related to that, but I think whenever the fields from the opsi boot image were auto filled via DHCP (screen with blue background) the input stopped working and I had to reboot until they weren't automatically filled out.

Where did the input stop?
If we get all required network configuration through DHCP we assume this configuration is correct and the user doesn't have to do anything - we want an unattended installation after all.
Depending on the netboot product there might still be questions asked like "Do you want to install xyz". Did you get such a question and then weren't able to answer that question?


Kind regards

Niko
Kein Support per DM!
_________________________
opsi support - uib gmbh
For productive opsi installations we recommend support contracts.

Bas
Beiträge: 4
Registriert: 02 Mai 2018, 10:25

Re: Feedback on (mostly) documentation

Beitragvon Bas » 09 Mai 2018, 14:26

Halöle!

Bas hat geschrieben:If dialogues doesn't pop up during server installation, dpkg-reconfigure might help (p. 13), esp. aftpd. I am not sure how necessary this is, or if the configuration simply happens at a later time else.

These dialogues are optional and you usually will be able to reconfigure these parts later on through configuration files.

Maybe it would be wise to correect this in the doc to avoid confusion.



n.wenselowski hat geschrieben:
Bas hat geschrieben:PXE booting: Consider stating that the error "SIOCDELRT: No such process" doesn't affect functionality.

When did this message appear to you?

I think in the black (?) screen after choosing the pxe boot medium before the blue screen with the input fields.

n.wenselowski hat geschrieben:
Bas hat geschrieben:The guide in the docu regarding opsi-scripts and how to install new opsi-products is too detailed. It was, to say the least, overwhelming to read when you just want to create a simple opsi package. I think it might be beneficial to reduce it to something like this simple Firefox setup code:
wiki/doku.php?id=userspace:firefox

I disagree in this case. Having someone to just copy a script without understanding why the things in the script are the way the are and where to place what part of an opsi package educates people so they can later on create their own scripts.
But you have a point in the guide being maybe a tad too extensive in some places. I'll see what can be done in this case to not overwhelm new readers.

The issue is rather that is simply too much for someone who probably just want to write a simple install script. Just compare the simple script in the wiki with the doc and you should see that less information should be sufficient and more fitting for what the user is probably trying to accomplish at that point.
My wish was surely to create a simple install script to even check if it works at all, and less so to implement 3k switches for more advanced configurations. (No offense)

n.wenselowski hat geschrieben:
Bas hat geschrieben:Creating WinPE by opsi doesn't seem to work for Win 7, only for 8 and above. The document doesn't really state this, so I had to figure it out for quite some time and was left outin the dark.

Could you elaborate a little bit on what you tried and what didn't work for you? The procedure is the same since Windows Vista and we've usually update the guide to work with the latest versions.

As written in the guide, I installed the WAIK @ W7 (32-Bit, though) and set opsi-winpe @ setup, and prob fired an on-demand event or rebooted. I assume I also did set the arch to x86 in the props, but can't tell for sure anymore.

n.wenselowski hat geschrieben:
Bas hat geschrieben:Maybe describe how the SSL cert should look like (opsiconf SSL cert), for instance, what a common name etc. is

I feel that this is somehow outside of the scope of the getting started. But on a properly configured server you can just OK all of the questions and continue. Would you think that this would be a helpful hint?

Sure!
Not sure if I ran into issues when I miss-configured that, but I think I did. That was on a freshly installed server.

n.wenselowski hat geschrieben:
Bas hat geschrieben:With the pxe boot image I used, I only had ONE (!) second to select a device before it went it autoboot mode and booted from HDD (after opsi boot image was found). Prob was the x86 boot image, can check if it helps.

This behaviour is intentianol. It is usually expected that if you want to i.e. install a netboot product on a client you set this product to setup in opsi and then you won't have to manually select that the bootimage should be booted.
If you think a larger timeout would help you can alter the file /tftpboot/linux/pxelinux.cfg/default.menu and change the timeout to something larger.

Wouldn't it make sense to have a larger timeout in general? I mean, otherwise you'd assume that LAN is like the first boot device - Who does that? (There might be configs where this is helpful, as I am just about to end my apprenticeship as Fachinformatiker Systemintegration and I might simply not have enough experience)

Bas hat geschrieben:When installing the opsi client, I had the issue that there was some window popping up (or not) in which the user is asked about some authentification information. Unfortunately, for me the window didn't seem to appear on the fore-, but rather the background - with no task bar entry either. There was no clear indication that there is some input required if there is nothing to see for the user. I suggest to at minimum create a task bar entry for that window. To find out about this did cost me roughly eight working hours. For the time being, it might prove helpful as a workaround to include a hint in the documentation.

I couldn't reproduce the behaviour that the window appears in the background. What OS did your client have? Does it have any settings aside from the Windows defaults that may change the behaviour?
I'll check what can be done to make it more prominent that input is required!

Win 7 x64. No clue about other things. VM is in use for quite some time, so in theory it could be anything, but afaik I tried to install the client at 2 machines at minimum, the other might be a fresh Win 7 x86 VM on the server.
I am also not 100%ly sure whether it appeared in the background or took like 60+ minutes to appear, but the former sounds way more likely. Possibly I clicked at another process window during the installation process, such as firefox. Did you test if the focus shifts to the login window if another process (not the setup) is in the foreground?

Info in doc or task bar entry would help quite a lot I guess.

Might try again for reproduction, but I don't want to make promises I can't keep.

Bas hat geschrieben:This was in a VM in virtualBox, so it might be related to that, but I think whenever the fields from the opsi boot image were auto filled via DHCP (screen with blue background) the input stopped working and I had to reboot until they weren't automatically filled out.

Where did the input stop?
If we get all required network configuration through DHCP we assume this configuration is correct and the user doesn't have to do anything - we want an unattended installation after all.
Depending on the netboot product there might still be questions asked like "Do you want to install xyz". Did you get such a question and then weren't able to answer that question?

I think for installation I was only asked about whether I want to install the configured netboot product (Win 7).
Would have to check to make absolutely sure, but I think no input whatsoever worked so I couldn't progress to other steps at all.
I'd also consider allowing input into these fields in case there are mistakes and errors, or just plainly to avoid user confusion.

n.wenselowski hat geschrieben:Hello Bas,

thanks for your feedback!
As for the documentation I tried to improve most of the things you mentioned and they should be available with the next documentation build so everyone can benefit.

Thanks for replying, this helps a lot for motivation when knowing your feedback is heard!

Answer is WIP, but I don't want to loose any process, so better submit now.

Bas
Beiträge: 4
Registriert: 02 Mai 2018, 10:25

Re: Feedback on (mostly) documentation

Beitragvon Bas » 09 Mai 2018, 14:53

Finished answer above /info.

Benutzeravatar
SisterOfMercy
Beiträge: 917
Registriert: 22 Jun 2012, 19:18

Re: Feedback on (mostly) documentation

Beitragvon SisterOfMercy » 10 Mai 2018, 01:48

Bas hat geschrieben:
n.wenselowski hat geschrieben:
Bas hat geschrieben:With the pxe boot image I used, I only had ONE (!) second to select a device before it went it autoboot mode and booted from HDD (after opsi boot image was found). Prob was the x86 boot image, can check if it helps.

This behaviour is intentianol. It is usually expected that if you want to i.e. install a netboot product on a client you set this product to setup in opsi and then you won't have to manually select that the bootimage should be booted.
If you think a larger timeout would help you can alter the file /tftpboot/linux/pxelinux.cfg/default.menu and change the timeout to something larger.

Wouldn't it make sense to have a larger timeout in general? I mean, otherwise you'd assume that LAN is like the first boot device - Who does that? (There might be configs where this is helpful, as I am just about to end my apprenticeship as Fachinformatiker Systemintegration and I might simply not have enough experience)


Who does that? Everybody!
Well, for computers with a non-UEFI boot anyway. (UEFI network boot is just so slooooww, but that's a different issue).

What you might not have seen is that if you set a netboot product to install in configed, the opsi server will create a special file (not sure if it's a pipe), so the next time that computer boots via PXE, it will use that file. So if all your clients are set to boot from LAN, they will get the normal boot menu, and start from the local drive, unless you have set a particular action to do via configed.
Bitte schreiben Sie Deutsch, when I'm responding in the German-speaking part of the forum!

Bas
Beiträge: 4
Registriert: 02 Mai 2018, 10:25

Re: Feedback on (mostly) documentation

Beitragvon Bas » 11 Mai 2018, 14:32

I think I had done that, yet I needed to switch to LAN boot within a sec nonetheless.