diff --git a/rc1/.DS_Store b/rc1/.DS_Store new file mode 100644 index 000000000..e3d2ff958 Binary files /dev/null and b/rc1/.DS_Store differ diff --git a/rc1/.gitignore b/rc1/.gitignore new file mode 100644 index 000000000..5c96c8016 --- /dev/null +++ b/rc1/.gitignore @@ -0,0 +1,2 @@ +# +*.html diff --git a/rc1/Makefile b/rc1/Makefile new file mode 100644 index 000000000..e977a90d8 --- /dev/null +++ b/rc1/Makefile @@ -0,0 +1,32 @@ +# +# Copyright (c) 2020, 2022 NVI, Inc. +# +# This file is part of FSL10 Linux distribution. +# (see http://github.com/nvi-inc/fsl10). +# +# This program is free software: you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation, either version 3 of the License, or +# (at your option) any later version. +# +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. +# +# You should have received a copy of the GNU General Public License +# along with this program. If not, see . +# + +DOC_DIR = releases misc + +.PHONY: all $(DOC_DIR) + +all: index.html $(DOC_DIR) + +$(DOC_DIR): + $(MAKE) -C $@ + +%.html: %.adoc + asciidoctor $^ + diff --git a/rc1/drafts/.DS_Store b/rc1/drafts/.DS_Store new file mode 100644 index 000000000..010d4780a Binary files /dev/null and b/rc1/drafts/.DS_Store differ diff --git a/rc1/drafts/releases/.DS_Store b/rc1/drafts/releases/.DS_Store new file mode 100644 index 000000000..2eef5e8c4 Binary files /dev/null and b/rc1/drafts/releases/.DS_Store differ diff --git a/rc1/drafts/releases/10/.DS_Store b/rc1/drafts/releases/10/.DS_Store new file mode 100644 index 000000000..a7e706d67 Binary files /dev/null and b/rc1/drafts/releases/10/.DS_Store differ diff --git a/rc1/index.adoc b/rc1/index.adoc new file mode 100644 index 000000000..2996419f5 --- /dev/null +++ b/rc1/index.adoc @@ -0,0 +1,32 @@ +// +// Copyright (c) 2020, 2022, 2023 NVI, Inc. +// +// This file is part of the FSL10 Linux distribution. +// (see http://github.com/nvi-inc/fsl10). +// +// This program is free software: you can redistribute it and/or modify +// it under the terms of the GNU General Public License as published by +// the Free Software Foundation, either version 3 of the License, or +// (at your option) any later version. +// +// This program is distributed in the hope that it will be useful, +// but WITHOUT ANY WARRANTY; without even the implied warranty of +// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +// GNU General Public License for more details. +// +// You should have received a copy of the GNU General Public License +// along with this program. If not, see . +// + += Index of fs/ +Version 0.9 - August 2023 + +== Direct Links + +<> Update Notes (latest release) + +== Links to sub-directories + +<> sub-directories + +<> documents diff --git a/rc1/index.html b/rc1/index.html new file mode 100644 index 000000000..53dd05904 --- /dev/null +++ b/rc1/index.html @@ -0,0 +1,474 @@ + + + + + + + + +Index of fs/ + + + + + +
+
+ +
+
+

FS 10.2 Update Notes (latest release)

+
+
+
+
+ +
+
+

Release sub-directories

+
+
+

Miscellaneous documents

+
+
+
+
+ + + \ No newline at end of file diff --git a/rc1/making_gh-pages.txt b/rc1/making_gh-pages.txt new file mode 100644 index 000000000..52b3bcc7b --- /dev/null +++ b/rc1/making_gh-pages.txt @@ -0,0 +1,37 @@ +// +// Copyright (c) 2020, 2022, 2023 NVI, Inc. +// +// This file is part of the FSL10 Linux distribution. +// (see http://github.com/nvi-inc/fsl10). +// +// This program is free software: you can redistribute it and/or modify +// it under the terms of the GNU General Public License as published by +// the Free Software Foundation, either version 3 of the License, or +// (at your option) any later version. +// +// This program is distributed in the hope that it will be useful, +// but WITHOUT ANY WARRANTY; without even the implied warranty of +// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +// GNU General Public License for more details. +// +// You should have received a copy of the GNU General Public License +// along with this program. If not, see . +// + +Requires asciidoctor + +Source in docs/ + +To update when commit is finished: + + git branch -f gh-pages + is whatever is to be used, usually main + git checkout gh-pages + make + git add -f $(find . -name \*.html) + git commit -m Update + git push --force + +View at: + +https://nvi-inc.github.io/fs/ diff --git a/rc1/misc/64-bit_conversion.adoc b/rc1/misc/64-bit_conversion.adoc new file mode 100644 index 000000000..2113678df --- /dev/null +++ b/rc1/misc/64-bit_conversion.adoc @@ -0,0 +1,605 @@ +// +// Copyright (c) 2020-2023 NVI, Inc. +// +// This file is part of VLBI Field System +// (see http://github.com/nvi-inc/fs). +// +// This program is free software: you can redistribute it and/or modify +// it under the terms of the GNU General Public License as published by +// the Free Software Foundation, either version 3 of the License, or +// (at your option) any later version. +// +// This program is distributed in the hope that it will be useful, +// but WITHOUT ANY WARRANTY; without even the implied warranty of +// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +// GNU General Public License for more details. +// +// You should have received a copy of the GNU General Public License +// along with this program. If not, see . +// + += Converting to a 64-bit System +Version 1.9.1 - September 2023 + +//:hide-uri-scheme: +:sectnums: +:sectnumlevels: 4 +:experimental: + +:toc: +:toclevels: 4 + +:sectnums!: +== Document revision history + +Click the *Details* toggle below to unhide/hide the history. + +[%collapsible] +==== + +* 1.9.1 -- Add *NOTE* about not renaming _/usr2/log_ +* 1.9 -- Remove extraneous `log-old` from `chmod a-w ...` +* 1.8 -- Improve customization of home directories; put Document revision history in a collapsible block +* 1.7 -- Note other formats for `_st-version_` +* 1.6 -- Transfer logs directly to a reference copy +* 1.5 -- Use _root_ on the old system to copy files if possible +* 1.4 -- Add revision history +* 1.3 -- Rewrite to include FSL11 and make useful for more situations +* 1.2 -- Add using ssh-keygen +* 1.1 -- Cleanup +* 1.0 -- Add unlongify TIP +* 0.8 -- Fix typos +* 0.7 -- Font improvements +* 0.6 -- Simplify 64-bit upgrade path +* 0.4 -- Simplify 64-bit upgrade path +* 0.3 -- Initial version + +==== + +:sectnums: +== Introduction + +This document covers converting to a 64-bit system architecture from +an existing FS _10._ installation on a 32-bit system. It is also +used as part of the upgrade path to go directly to a 64-bit system +while upgrading to FS _10.0_. + +The approach here can also be used to transfer an existing 64-bit (or +32-bit) FS installation to a new computer without changing OS +(including architecture) and FS version. For that case, in place of +the <> step make sure you have the same OS +(including architecture) and FS version installed on your new system +as on your existing system and then omit the +<> step. + +If you are moving to a different OS, you may need to use a different +FS version and update your station files and software for the new OS +and FS version. For FSL11, a pointer to the instructions for this are +included in its installation guide and in the +<> step below. + +The process in this document assumes you will be installing to a new +computer. This will allow you to set up the new system without +disturbing your operational system. + +== Convert to using a 64-bit system + +IMPORTANT: All operations, except where noted, are performed on the +new system. + +Please follow the steps below. + +=== Install a 64-bit system + +Install a 64-bit (or 32-bit, but 64-bit is recommended) system on a +different (hopefully new) computer. We recommend FSL11, which is based +on Debian _Bullseye_ and tuned for FS use. The FSL11 installation +guide can be found at https://nvi-inc.github.io/fsl11/. That process +installs FS _10.2_. After that instead of the directions in the +current document, you should follow the directions in the appendix +<<../releases/10/2/10.2.adoc#_transferring_an_existing_fs_installation_to_fsl11,Transferring +an existing FS installation to FSL11>> of the +<<../releases/10/2/10.2.adoc#,FS 10.2 Update Notes>> document. Those +instructions include, by reference, a subset of the ones in the +current document. + +NOTE: If you are following these directions as part of installing FS +_10.0_ on FSL10, that will still work, but we recommend using FS +_10.2_ on FSL11 instead. + +You can install a non-FSL__X__ Linux distribution. However, we can't +provide as much support in that case. The FSL11 distribution is tuned +to provide a complete platform for running the FS. For other +distributions you may have to make adjustments for several things that +an FSL11 installation provides, including: + +- which packages are installed +- required user accounts and groups +- backup methods + +=== Login as root on the new system + +Login as _root_ on the new system. + +=== Rename default directories + +NOTE: This step assumes you have installed a base FS, either along +with FSL11 or using your own methods. If the latter and the normal +default FS directories were not created, you can skip this step. + +. Rename the existing default station specific FS related directories +on the new computer to get them out of the way: + + cd /usr2 + mv control control.DEFAULT + mv sched sched.DEFAULT + mv proc proc.DEFAULT + +. If you use the _/usr2/tle_files_ directory on your old computer, +you should rename the one on the new computer: + + cd /usr2 + mv tle_files tle_files.DEFAULT + +. If your station software is in _/usr2/st-0.0.0_ on your old computer, +you should rename the one on the new computer: + + cd /usr2 + mv st-0.0.0 st-0.0.0.DEFAULT + +NOTE: The _/usr2/log_ directory is not renamed since the transfer of +that directory from the old computer will not replace the one of new +computer. Instead, it will directly create a reference copy, as +_/usr2/log-old_. + +=== Transfer files + +Your station specific FS related files can be transferred from the old +computer using any convenient method. If both systems are on the +network this can be particularly easy. The following example sub-steps +use this approach. You should replace the `_old_` host name in the +examples with your old system's host name. These commands must be +executed as _root_, and except where noted, from the new system. + +TIP: For the reference copies of the old computer directories, the +instructions use directory names on the new computer with a fixed +string `-old` appended. You may prefer a different suffix, e.g., one +that includes the name of your old computer. + +[NOTE] +==== + +You may need to provide the appropriate password for each _scp_ +command below. If so, you can simplify the process by copying your +new computer's _root_ public SSH keys to the old machine _oper_ and +_prog_ accounts with _ssh-copy-id_ first. If _root_ doesn't have an ID +yet, you will get an error like: + + /usr/bin/ssh-copy-id: ERROR: No identities found + +In that case, you can generate a key with _ssh-keygen_ +(leaving the passphrase empty is recommended) and try _ssh-copy-id_ +again. + +==== + +CAUTION: It is assumed that the new installation is on new hardware +with disks more than large enough to accommodate all the data being +transferred. However, if you installed the new Linux on old hardware +with small disks, there may be a space issue. + +WARNING: The instructions below assume that the existing system you +are using has a standard FS configuration in terms of symbolic links +and directories. If your system is different, you will need to adjust +what you do accordingly, but you may still find the outline of steps +useful. + +IMPORTANT: These instructions assume that you can login to the old +system as _root_ using _ssh_. Allowing this is a security risk and +should only be allowed temporarily for these command. If you are not +able to allow it temporarily, you can use the _oper_ and _prog_ (or +other) accounts as appropriate to transfer the files. In that case, +there is risk that some files may not be copied due to +ownership/permission issues. You may need to take other steps to copy +those files. + +. Transfer operations directories: + +.. Transfer _control_, _sched_, and _proc_ from your `_old_` computer: + ++ + +[subs="+quotes"] +.... +cd /usr2 +scp -pqr root@_old_:/usr2/control . +scp -pqr root@_old_:/usr2/sched . +scp -pqr root@_old_:/usr2/proc . +.... ++ + +NOTE: Your _sched_ and _proc_ directories could be +large and take a significant amount of time to transfer. + +.. Transfer _log_: ++ + +It can be useful to have your old log files on the new computer. The +commands below transfer the logs on your old computer to be a +reference copy on the new computer. The transfer from your `_old_` +computer could take a long time: + ++ + +[subs="+quotes"] +.... +cd /usr2 +scp -pqr root@_old_:/usr2/log log-old +chown -R oper.rtx log-old +chmod -R a-w log-old +.... + +.. Transfer _tle_files_: ++ + +If you use the _/usr2/tle_files_ directory on your `_old_` computer, +you can also transfer it: + ++ + +[subs="+quotes"] +.... +cd /usr2 +scp -pqr root@_old_:/usr2/tle_files . +.... + +. Fix the permissions on the operations directories/files you +transferred. You can fix their permissions and ownerships +to the standard with: + + /usr2/fs/misc/fix_perm ++ +Answer `*y*` to confirm. ++ + +NOTE: If you don't have a _/usr2/tle_files_ directory, you will get a +message that there is no such directory. That is benign unless you +expect such a directory to be there. + +. Make back-up copies of the operational directories. This sub-step is +optional but may be useful so that there are unmodified copies of the +directories from the old machine to use for reference. You may want to +set their permissions so they can't be modified accidentally. + ++ +[subs="+quotes"] +.... +cd /usr2 +cp -a proc proc-old +cp -a control control-old +cp -a sched sched-old +chmod -R a-w proc-old control-old sched-old +.... + ++ + +and possibly: + ++ +[subs="+quotes"] +.... +cd /usr2 +cp -a tle_files tle_files-old +chmod -R a-w tle_files-old +.... + +. Transfer your station software directory (and make a +reference copy). This is usually the target directory +pointed to by the _/usr2/st_ symbolic link. On your old +computer, you can find its name with: + + ls -l /usr2/st ++ + +In the rest of this sub-step, the target `_st-version_` will be used. +You should replace `_version_` with your version string. For example, +use `_1.0.0_`, to make a target `_st-1.0.0_`. (You may need to adjust +these commands if you have a different format for `_st-version_`, +perhaps `_st-git_`.) If your target is `_st-0.0.0_` you should rename +the default on the new computer first as described in the +<> step above. + +.. On the new computer, copy the target from the `_old_` computer to +the new computer, e.g.: + ++ + +[subs="+quotes"] +.... +cd /usr2 +scp -pqr root@__old__:/usr2/st-_version_ . +.... + +.. On the new computer, set the _/usr2/st_ symbolic link to point to +the target directory: ++ + +[subs="+quotes"] +.... +cd /usr2 +ln -fsn st-_version_ st +.... + +.. On the new computer, you should set its ownership and prevent users +other than _prog_ from modifying it: + ++ +[subs="+quotes"] +.... +cd /usr2 +chown -R prog.rtx st-_version_ +chmod -R go-w st-_version_ +.... + +.. On the new computer, you can make a reference copy and prevent it +from being modified with: + ++ + ++ +[subs="+quotes"] +.... +cd /usr2 +cp -a st-_version_ st-_version_-old +chmod -R a-w st-_version_-old +.... + +. Copy your _oper_ and _prog_ directories to the new computer. This +sub-step is optional. The FSL11 installation made default home +directories for these users on _/usr2_. If you did not have customized +content for the users on the old computer, you could just use the +versions on the new computer. Still it may be useful to have a copy of +your old directories on the new system for reference, especially if +you realize later that there were additional programs and files you +want to use on the new system. In the commands below `_old_` is the +name of your old computer. + +.. You can accomplish the transfers as _root_ using: ++ + +[subs="+quotes"] +.... +cd /usr2 +scp -pqr root@_old_:~ oper-old +scp -pqr root@_old_:~ prog-old +.... + +.. You probably want to set their ownership and prevent them from +being modified accidentally: + ++ + +[subs="+quotes"] +.... +chown -R oper.rtx /usr2/oper-old +chmod -R a-w /usr2/oper-old + +chown -R prog.rtx /usr2/prog-old +chmod -R a-w /usr2/prog-old +.... + +.. Customize the home directories on the new computer to include any +features you want from the old system. + ++ + ++ + +This would typically include updating the default _~/.profile_, +_~/.bashrc_, _~/.bash_aliases_, and _~/bin_. If you were previously +using _tcsh_ (the default for FSL9 and earlier) and are now changing +to _bash_ (the default for FSL10 and later), you will need to +translate customized settings from your _~/.login_ and _~/.cshrc_ +files. + +. At this point you are principle done transferring files. +However, it is also possible that you may need or want +other files or changes such as: + +.. Copy other files or programs from the old system ++ + +This might include directories and log files that exist as copies from +even older computers. You can use a similar process to the one above. +If you have enough space and can _ssh_ into your old computer as +_root_ (which should only be allowed temporarily), you can make +reference copies of the entire _/etc_/ and _/usr2_ directories from +your `_old_` computer with: + ++ + ++ +[subs="+quotes"] +.... +cd /usr2 +mkdir OLD_PC +cd OLD_PC +scp -pqr root@_old_:/etc . +scp -pqr root@_old_:/usr2 . +chmod -R a-w /usr2/OLD_PC +.... + +.. Install additional Debian packages +.. Copy/merge additional configuration files, such as: + + /etc/hosts + /etc/hosts.allow + /etc/hosts.deny + /etc/ntp.conf + +=== Login as prog on the new system + +Login as _prog_ on the new system. + +=== Update station programs for 64-bit + +This step is for modifying your station programs in _/usr2/st_. There +are two possible issues, conversion of FORTRAN code and conversion of +C code. + +NOTE: If you are not converting from 32- to 64-bit, you should skip +this step and go directly to the <> step below. + +==== Conversion of FORTRAN code + +If you don't have any FORTRAN station code or you have already +converted it to _f95_, skip this sub-step. + +Use of _f95_ is necessary +on 64-bit systems. If you have station programs +in FORTRAN, please email Ed so he is aware. + +You will need to adapt your __Makefile__s +to use the same compiler options as the FS, which can be +found in _/usr2/fs/include.mk_. +As a first cut, it may work to add the following two lines +to your __Makefile__s for FORTRAN programs: + + FFLAGS += -ff2c -I../../fs/include -fno-range-check -finit-local-zero -fno-automatic -fbackslash + FLIBS += -lgfortran -lm + +==== Conversion of C code + +If you don't have any C station code, you can skip this sub-step. + +If you have C station code, it should work as written unless +you have declared integers that interface to the FS as `long`. +For a start at fixing those, please see +https://github.com/dehorsley/unlongify. +The following steps describe how to install and use the _unlongify_ tool. + +===== Install go language + +If you haven't already, you will need to first install the _go_ +language. If you are using FSL11, you can install the _go_ language in +one of two ways listed below: + +. <