Attended sysupgrade documentation

Hello,

Looking at this documentation page:

I've used Attended sysupgrade twice now, and it works wonderfully, but the web GUI information via LuCI gets frozen. See screenshot below. I do not know if this is normal behavior.

If this is the expected behavior of Attended sysupgrade...
Is it possible to get the documentation to reflect that this is what happens in the process? And once your router reboots, you can just close the LuCI tab and log back in again via LuCI or SSH.

Thank you.

It is normal behavior. It seems obvious that the software has to upgrade at some point in time; but I agree it's not noted on the GUI.

Yes, feel free to add those details. See:

Since the router reboots afterwards, I'm not sure how that would be possible - perhaps "you may need to reconnect after X time if LuCI doesnot refresh". My only concern would be that people interrupt the flash process prematurely or they installed an image without the web GUI (i.e. the page will never reload, lol).

1 Like

Hello lleachii,

Thank you for your reply. I've just applied for a wiki account.

Since the router reboots afterwards, I'm not sure how that would be possible - perhaps "you may need to reconnect after X time if LuCI doesnot refresh". My only concern would be that people interrupt the flash process prematurely or they installed an image without the web GUI (i.e. the page will never reload, lol).

A few things occur to me as possibilities.

The first is on the technical software side. Please understand that I am not a programmer, so I don't know what is possible with all this.

Is the attended sysupgrade process software limited in such a way that it cannot inform LuCI, or the CLI that it has finished upgrading and is restarting the router?

If not, could this possibly be a suggested new feature?

Potential documentation changes to reflect the current state of Attended Sysupgrade:

My feeling is you have to document all the details of the process so the user is not left wondering what is happening, or what they should do. On top of that, give a standard warning of: "You may brick your device, or at the very least cause the OpenWRT upgrade to be inoperable if you do x,y, or z during the upgrade process."

I don't know all the circumstances that would cause the above warning to occur, but the following list is the obvious stuff to me.

  • Router losing power, or being intentionally powered off during the upgrade.

  • Router being being force restarted via a hardware reset button, like is typical on x86 hardware, during the upgrade.

Are there any other circumstances that you, or anyone else knows that could cause the upgrade process to fail leaving the router bricked, or inoperable without a fresh install of OpenWRT being applied? Does closing out the LuCI browser tab in the upgrade process, or the SSH session in a CLI version of this cause problems?

Ideas about how to let the user know when it is ok to close out LuCI, or the SSH session, as the upgrade process has finished.

  • If you can access the internet again through the router, then the upgrade process has finished.

  • If you upgraded through LuCI, and you are able to log into OpenWRT via SSH and it shows the new version, then the upgrade process has finished.

  • If you carefully watched the lights on your router (assuming they worked properly beforehand), and saw all the lights on the router going out briefly and then slowly coming back on in the expected sequence of a restart, or power on cycle.

  • And yes, your idea of wait x amount of time before closing out LuCI, or the SSH session. (So far in my experience on x86, LuCI does not ever refresh automatically after the upgrade process.) If using this, I think we'd want to get a developer to give us a worst case time estimate of doing an attended sysupgrade on the slowest write speed flash hardware that is officially supported by the stable and old stable builds with the whole default rootfs size filled. I have no clue what a safe time estimate would be.

With all of the above, I'm open to polite constructive criticism, and other ideas I may not be aware of.

You are aware that during the upgrade, the firmware is being completely re-flashed with the new image, correct?

Then the device reboots to load/use the new image. There is no old web GUI/web server running to send subsequent messages to the web browser. This is normal behavior for all firmware-based devices when upgrading.

Since the screen you displayed would be the last opportunity - that's why I suggested the verbiage be noted regarding that step.

Usually:

  • The LuCI web GUI can be reloaded
  • You can SSH again

:spiral_notepad: This is dependent on the the image containing LuCI and you using the same IP address. That's simply not possible in a lot of scenarios. It also depends on the client itself (e.g. if you upgrade from Wireless - if resetting configs, WiFi will be disabled on reboot). Neither dependency is guaranteed to be the same in every circumstance. So the fact you are not notified could be client connectivity, HTTP(S) timeout, etc.

Actually, the SSH session automatically closes itself (and all other shell sessions) at the appropriate time. It does inform you that it's closing the session. I haven't read the Wiki regarding CLI in a while, but it's kinda common knowledge for embedded devices that it will reboot during the firmware upgrade process.

1 Like

You are aware that during the upgrade, the firmware is being completely re-flashed with the new image, correct?

Yes I am.

Then the device reboots to load/use the new image. There is no old web GUI/web server running to send subsequent messages to the web browser. This is normal behavior for all firmware-based devices when upgrading.

Since the screen you displayed would be the last opportunity - that's why I suggested the verbiage be noted regarding that step.

Ah ok, that makes sense. I did warn you that I am not a programmer, so I don't know exactly what is going on in the hardware and software while this all happens. Thank you for explaining. So there is a technical limitation of what is possible here for messaging the user in this process.

This is dependent on the the image containing LuCI and you using the same IP address. That's simply not possible in a lot of scenarios. It also depends on the client itself (e.g. if you upgrade from Wireless - if resetting configs, WiFi will be disabled on reboot). Neither dependency is guaranteed to be the same in every circumstance. So the fact you are not notified could be client connectivity, HTTP(S) timeout, etc.

This is very good detailed information to know. Thank you for this. There is so many possible different setups with routers that I forget of different use cases, and configuration changes when resetting configs that might change how the device might operate after the upgrade.

The way I see it, if those are the only two feasible options, then we spell out all the dependents for that to happen such as you mentioned.

Yes, but does the user closing it out before the Attended Sysupgrade does it itself at the appropriate time cause the upgrade to fail?

Agreed. Though slightly off topic here, I believe in terms of documentation, you should never assume the user has a certain common knowledge. This keeps users from succeeding with what they need, and new users from getting onboard and learning how to use OpenWRT, or any other project.

As an example, while I've been using Linux operating systems for roughly fifteen years, I still encounter things I've never seen before, things I just know nothing about, or things that changed in the way they work with new software versions. And often times in documentation, or forum support, there is pieces of knowledge that are assumed the user knows, so it is left out. This makes it more difficult, time consuming, and frustrating for me to move forward with resolving an issue when I have to look up either how to do this common knowledge thing, or why I'm getting an error when doing this next step.

I find myself somewhat confused now as to how would be best to edit the Attended Sysupgrade documentation page. I fully recognize that I do not know everything about how OpenWRT works, hence need input from other experienced people here to fill me in on what I do not know.

I also don't know what the process is with changing documentation once I get a wiki account, so bear with me in my ignorance with all of this.

1 Like

To be honest, I'm not sure how "closing it out before the Attended Sysupgrade does it itself" would even be possible. I don't understand this concern you're expressing. I would have to measure the time the process takes here.

:warning: To be clear, it's generally not advisable to interrupt any flashing process - again, this is common knowledge and best practice in the realm of embedded device upgrading. Interrupting a flash process can hard brick the device (i.e. rending it unusable - and creating a very expensive paperweight, in fact the phrase "expensive paperweight" is used in the IT field to describe such a failed device).

I'm not sure what this means, but I agree its cool to add more infomration for the user to comprehend.

:+1:

OK...I'm just not sure how one doesn't know the device will reboot - but I guess people have to learn somewhere - even if it's flashing an embedded device. Personally, I'd consider that quite advanced (i.e. the nuances should be known, you need to know Hex if there's a failure in some cases, how to use TTL serial, use the bootloader, etc.).

  • Login
  • Browse to page
  • Edit

Feel free to ask in the Wiki account thread.

1 Like

Flashing times vary widely, depending on the devices (type of flash, size of flash, flash speed/ bus frequency, sector size, to-be-written image size), as does the time needed to reboot, to firstboot (cryptographic key generation, …).

2 Likes

Ah, I see. This was poor wording on my part. I was thinking in terms of accidentally, or intentionally closing out the LuCI web page that Attended sysupgrade was started in before the image flashing is done. The reason I was asking this is from my second post in this forum thread that is quoted below.

The thought being, in the documentation, lets be very clear about what may cause Atteneded sysupgrade to fail, because once the flashing process starts, the user will no longer get any new messaging to tell them when it has finished. This question had no relation to how long it takes to flash an OpenWRT image.

Agreed. I personally know and understand this, but not everyone will. Again, I think it is poor form to assume everyone knows the basics of flashing embedded devices. When I write instructions up, I try to keep a perspective of a new user that does not know what they are doing in mind.

Depending on opinions of how documentation should be written, some users with plenty of knowledge and experience may find this overly wordy and get in the way of them getting the task done quickly. Such that we may want to provide a brief summary of what to do for those users first, which the Attended Sysupgrade documentation page mostly does already, and then go into more detail for less experienced users.

This was in relation to your prior comment about ideas of how to let users know when to safely close out the LuCI web page, or SSH session from your comment quoted below:

-------- Topic break

I understand where you are coming from with this. And maybe this begs the question of what audience we are trying to reach.

My thought is, if we don't make the documentation as easy, detailed, and obvious as possible, we miss out on gaining new users and having OpenWRT be more well known, popular, and used than it already is.

My casual observation of many amazing open source projects is that the lack of good documentation holds them back tremendously. And when you assume a certain amount of common knowledge in the documentation, this does the same thing. It keeps the level of entry high, so that only people with enough experience, knowledge, and determination to keep trying upon initial failure use OpenWRT. I'd like to see that change.

Whoops! Poor wording on my part again. As you mentioned in your last sentence, this may not be the correct place to ask this, but I'll clarify anyways in case it is relevant to this forum thread.

What I was trying to get at was not the literal process of how to edit documentation here, but the political process so to speak. Meaning, do documentation changes get put in a temporary hold for review by other members here before being officially applied to the web page?

While I do indeed want to help with this, I'm well aware that I do not know everything about OpenWRT, all the possible configurations it can do, and issues that may arise. I would want to make sure that other more experienced users review the changes I would potentially make. As my concern is accidentally putting up incorrect information that would guide a user into bricking their device. I've already seen that there is enough difference between the x86 version, and the other versions for dedicated router hardware that I've had issues with my understanding of how OpenWRT works with these other versions.


Hello slh, :slight_smile:

I assumed so to. The question in my mind being...

What is a best estimate of amount of time to tell the user to wait before closing out the LuCI web page and log back in, such as not to interrupt the image flashing process? This estimate has to surpass the slowest possible example of officially supported hardware.

On top of that, I do not have the knowledge to know whether the flashing time is increased, or the same if the default rootfs size is filled with user installed packages, versus just a few. Meaning, I don't know if writing empty space on flash is the same as is on a rotational hard drive or SSD for x86 where it does not take much time, or every sector of the flash has to be written to whether there is data there, or not.

1 Like

My situation also... I'm new 'round these parts, but hardly new to forums and community development projects. So, my strategy when assimilating a new culture (in this case OpenWrt) is to make a change to the best of my ability, then post in the appropriate forum, "Hey @maybe-reviewers, I hacked up the third paragraph in the Dingle page of the wiki. Could you take a look and see if I screwed it up?" After a while, I'll get comfortable with my level of expertise and only ask when needed. (I've been here about a year now, so I'll be asking for a wiki account soon and start adding bugs. :grin:)

1 Like