SwapSwapVM Read Me File

(last updated 18 May 2003)

WARNING: SwapSwapVM is currently in BETA status. Always check the website for the latest documentation and known issues!

NEWS

Latest version: SwapSwapVM_v0.9.9b9 for Mac OS X 10.2.0 through 10.2.6

20 May 2003 10:54MST:

SwapSwapVM 0.9.9b9 is now on the server; this version includes a pretty reliable workaround for the RC corruption bug found earlier today; if it fails, SwapSwapVM will lock itself and not allow you to make changes that could adversely affect your computer. Still, please run 'Simulation Mode' and look for obvious wierdness in the Virtual Memory section until we get more feedback on this version.

20 May 2003 09:05MST:

NOTICE: SwapSwapVM 0.9.9b8 has been temporarily pulled down; a recurring bug introduced with OS X 10.2.5, which delayed its release, appears to be present still on some systems. The bug produces a severe corruption in the RC output code, typically when a second simulation or RC modification is performed on a disk different from the first simulatuion or execution made during the same session-run of SwapSwapVM; i.e., if two or more disks are selected and executed without quitting SwapSwapVM, this error is prone to occur.

This corruption will render the Mac UNBOOTABLE, and thus should not be used except by advanced users who can inspect the RC output in a modified file prior to Restarting (or via the shell/pico on the way in).

We'll keep working on the problem, and hopefully have a solution within the day.

18 May 2003:


Sorry about the lengthy delay in releasing a new version; the developer was in the middle of moving offices, and SQ was in the middle of finals.

OS X 10.2.5 and 10.2.6 introduced a slew of bugs with the data-gathering aspects of SSVM, but not the actual RC code generated by SSVM; however, wide-spread kernel panics due to USB, SCSI and other peripherals were time-consuming to separate from possible issues with SSVM's RC code. In the end, SSVM was found to be innocent of all issues introduced with upgrades past 10.2.4.

We've added an option to 'Show All Disks', which overrides SSVM's "intelligent" examination and evaluation of various disks and their mounting order, which is intended to prevent one from using disks that mount too late in the boot process to be used as swap disks. Use it with caution; though if a disk fails to boot in time, swap will default to boot, you will need to examine the log and/or launch SSVM again to verify swap settings are as you wish.

NOTE: While the documentation has been mostly updated, some older images and minor notes still exist. If you have any questions, or spot any erroneous info, please let us know.

Download New Version (0.9.9b9)

What's new?

13 February 2003:
The beta testing period has been a great success! Only a few rare and unusual bugs have been reported; nothing critical resulting in a computer that won't start has been discovered. SwapSwapVM now also offers complete logging proof of its successes and failures.

Still, you should exercise caution and READ and UNDERSTAND these instructions before you proceed; you may further wish to use this utility only if you are reasonably experienced with OS X and comfortable with the possibility of very light use of the command line in the event of an emergency.


Table of Contents
What is SwapSwapVM?
Why would I use SwapSwapVM in the first place? Other people say changing Virtual Memory settings is pointless, and even dangerous.
How much does SwapSwapVM cost?
Why did you write SwapSwapVM?
Why should I use SwapSwapVM instead of other utilities or my own hacks?
Is it compatible with other utilities and hacks that alter Virtual Memory (swapfile) settings?
Which of my disks or volumes should I use for SwapSwapVM Virtual Memory (swapfile) targeting?
How do I use SwapSwapVM?
Simulation Mode
Running SwapSwapVM for Real
Issues for Advanced Users
Problems using FireWire Drives
Resetting Virtual Memory to Default
Restoring Original Virtual Memory Settings
Error Messages while running SwapSwapVM
Possible Future Additions to SwapSwapVM
Version History
Sample Code
What to do if your computer won't Startup
License and Disclaimer

What is SwapSwapVM?

SwapSwapVM is an AppleScript application made with Smile written to change the target volume (disk; partition) for the Virtual Memory swapfiles in OS X 10.2.x Jaguar. It has been vigorously tested on various configurations under OS X 10.2.0 through 10.2.4.

SwapSwapVM requires a default installation of OS X 10.2 through 10.2.4 Jaguar (including BSD) and a minimum 832x624 screen resolution.

• Aqua application interface; made with Smile 2.5.1
  
• Ability to use disks with space characters in the name
  
• Extensive error handling:
  
• -- error handling and checking for autodiskmount
  
• -- error handling to safely clear old unused swapfiles
  
• -- error handling to safely protect against removed or renamed disks
  
• Repairs improper settings installed by other utilities, such as Xupport 1.2.4 and older
  
• Includes 'simulation mode' to examine code output before executing
  
• Performs logging of successes and errors written to /Library/Logs
  
• Extensive documentation

SwapSwapVM was written by Frederico and student interns for ScienceQuest, with Special Thanks to William Faulkner.

Why would I use SwapSwapVM in the first place? Other people say changing Virtual Memory settings is pointless, and even dangerous.

They're wrong. Changing your Virtual Memory disk target to a dedicated, fast volume (partition; disk) is loaded with benefits, and has no appreciable drawbacks.

For example, by retargeting your Virtual Memory to another volume, you can free up precious space on your Startup volume (partition; disk), and reduce the frequency of "disk-thrashing", System slowdowns and wake-from-sleep errors (at least those instigated by memory leaks); quite possibly you'll prevent the need to repartition a volume, or reinstall OS X elsewhere, because the current Startup volume is too small for OS X and Virtual Memory, both.

Remember, Virtual Memory files are also created when you print from many applications to many common printers. The more you print, the bigger the print jobs are, the more Virtual memory space (and speed) you need.

Those people that claim that OS X will never create more than just one Virtual Memory swapfile equalling 80MB (76.2MB actual) are just plain wrong; if that is true for them, they never use heavy applications or print jobs that generate more memory use than they have installed physical memory capacity.

It is absolutely true that if you are continually generating more than one or two swapfiles, that you should install more physical RAM; however, you can only install as much RAM as your system is designed to hold. Even brand new PowerMac G4s with 2GB of RAM will generate multiple swapfiles; especially if you are a professional or prosumer using numerous applications and large jobs. We routinely find ten, twelve, fifteen and even twenty-five or more swapfiles on pro rigs with maximum physical RAM installed. These machines would be crippled if it were not for using fast, dedicated swap volumes.

An article discussing further pros and cons will be published in the near future. For now, you'll just have to trust us that this is a Good Thing.

How much does SwapSwapVM cost?

SwapSwapVM is "donationware". You can pay as little (US$1) or as much as you feel it benefits you. Your donations will go to ScienceQuest, a non-profit organization specializing in science education in the Rocky Mountain region; also a provider of free Mac support.

If you are a student or teacher using your Apple Computer for educational purposes, however, it's absolutely free.

If you are a consumer, professional, or especially a consultant or IT manager using SwapSwapVM to make your computer run better (and probably getting paid to use SwapSwapVM or reap its benefits), then you really, really, really ought to make a donation of some amount.

If you use it on more than one computer (and we're talking to you, you consultants and IT guys who use the heck out of shareware on your client computers without ever paying a dime), you should think about donating a whole bunch at least once, or a little bit each time you use it.

Basically, if you use SwapSwapVM even just once, unless you reverse its settings, you will essentially be using SwapSwapVM each time you use your computer. Please consider this when you decide whether or not to compensate in some way for its use.

If you are very, very poor, you are not obligated to pay anything; but, please ask yourself, if you're that strapped, how can you afford a Mac running Jaguar? If you really are unable to donate even a dollar, please at least send an email to stating your appreciation for SwapSwapVM, or consider donating some time or resources to a local school or nonprofit educational organization.

http://www.sciencequest.org/donations
SwapSwapVM@sciencequest.org

Why did you write SwapSwapVM?

Frankly, only because J. Schrier has (as of this writing) failed to release a new version of Swap Cop that is compatible with OS X 10.2.x Jaguar. We also wanted better error handling than Joshua ever used before, as well as some other features and behaviors. If Swap Cop is ever updated and has all the features we want, further development of SwapSwapVM will likely cease.

Why should I use SwapSwapVM instead of other utilities or my own hacks?

SwapSwapVM is superior to all other current utilities (as of this writing) because it is the only utility that will safely retarget the Virtual Memory swapfiles, safely remove the old, unused swapfiles, and it even includes special error checking code to revert to the default Virtual Memory settings if something goes wrong; e.g., if the target disk is removed or renamed, or should never have been used in the first place.

If you've ever used a utility or a manual hack that resulted in a grey or blue screen with (or without!) a bash line, then you know the frustration SwapSwapVM is designed to avoid.

SwapSwapVM also handles volumes with space characters in the name.

SwapSwapVM also includes logging and warning file installation on successes and errors.

SwapSwapVM will also safely preserve modifications made to RC that are unrelated to Virtual Memory.

SwapSwapVM includes a 'simulation mode' that will let you see the changes before they are executed; you will be able to read and compare your existing RC file with a proposed modified RC file.

Finally, SwapSwapVM includes the option to make the swapfile directory either visible or invisible; the visible option allows the user to more easily monitor the number of swapfiles created, and allows for easy identification and deletion in the odd event that SwapSwapVM fails to clean up after itself, such as if you (or some bad, bad person) renames the specified disk for Virtual Memory swapfiles.

Is it compatible with other utilities and hacks that alter Virtual Memory (swapfile) settings?

SwapSwapVM can successfully alter of even correct most settings and other errors caused by other utilities designed to modify the swapfile settings. In particular, it will fix the severe swapfile errors that may have been caused by using Xupport versions 1.2.4 and older. It will not repair incorrect settings to the App_Profile folders set by Xupport 1.2.4 and older (perhaps in a future version).

SwapSwapVM can also change settings installed in 'etc/rc' by Swap Relocator 1.0, but the current version will not remove the startup item in 'etc/hostconfig' that activates the Swap Relocator operation. You will need to manually uninstall Swap Relocator 1.0 changes (see its read me file) for SwapSwapVM changes to fully take effect!! A version of SwapSwapVM that can fix Locator changes is scheduled for the future.

It will also correct basic issues caused by using Swap Cop 1.2 and older (those versions are not qualified for and will not work with OS X 10.2.x Jaguar, regardless of user claims). SwapSwapVM will not, however, remove a Startup item called 'Virtual Memory' installed by Swap Cop 1.x in /Library/Startup Items. An error will continue to appear in your Startup Screen titled 'VM already running! Check etc/rc'; you must remove this file manually. Alterations made by Swap Cop to the '/etc/hostconfig' file should not affect SwapSwapVM settings.

The only time SwapSwapVM is known to fail is if the existing '/etc/rc', 'etc/fstab' and 'etc/hostconfig' file(s) have been previously heavily modified (with respect to Virtual Memory settings). The most common modification it is not currently designed to repair is when someone has manually moved the entire VM section to the end of the RC file (a common tip found on many websites).

If you (or anyone else) have never manually modified your RC file, then you should not have to worry about the above potential problems.

Which of my disks or volumes should I use for SwapSwapVM Virtual Memory (swapfile) targeting?

An article discussing this in detail will be published shortly, but, basically, you should pick a volume or partition (disk) that is, if not your fastest, at least very fast. E.G, a FireWire 400 (50MB/sec max) disk would be very fast; a USB 1.1 (1.2MB/sec max) disk would be very slow; likewise, certain drives on your internal busses are faster or slower than others. E.G., a 7200RPM ATA drive on an ATA-66 bus of an older G4 PowerMac has a theoretical maximum throughput of 66MB/sec max, while the optical bus (EIDE-16) on the same model tops out at 16MB/sec. max.

Models vary, and you may have installed a fast PCI-ATA adapter card, or are even employing RAID 0 highly recommended!) to increase your drive speed. Or, you may have a PowerBook with only one drive; in this case, you will need to simply partition it (use FWB Partition Toolkit; US$20; avoids the need to erase the disk) and use a fast volume on the same disk.

You'll have to test your drive speeds on your own to see which is the best candidate. We recommend Xbench for testing volume throughput.

In addition, you will need to choose a volume that has sufficient free space to accommodate multiple swapfiles. You should choose a volume that has at least 500MB of free space (all the time), but it is better to be 2GB or more. Remember, one swapfile is 80MB; if you routinely generate ten swapfiles, you'd need 800MB of useable free space; if you generate twenty swapfiles, you'd need 1.6GB, etc.

And don't forget that you also need to have 15% of your volume's (disk) space free at all times, anyway (the Mac OS X HFS+ file system can generate errors if disk contents exceed 85%-90% of capacity), so a good formula for a swap volume (Virtual Memory disk target) is:

(maximum number of swapfiles created X 80MB) + 25% free safety space

E.G., 20 swapfiles X 80MB = 1600MB + 320MB = 1920MB (1.92GB or larger)
1920MB - 1600MB = 320MB ( approximately 17% free safety space)

In order to determine the number of swapfiles you generate on an extreme day, you'll need to open a bunch of applications, open a bunch of big files, and try to print the biggest files you'll ever print. While you're doing all this, you then run SwapSwapVM and red the 'Current Virtual Memory Settings'. It will return the file path to the current VM directory, and tell you the current number of swapfiles contained therein. You can then use the above formula to determine your ideal swap volume size.

NOTE: Due to a current permissions bug, SwapSwapVM may not be able to return the current number of active swapfiles on certain volumes under certain conditions. A future release will deal with this issue.

You can also try using the excellent freeware application 'Memory Stick' for a full-time, always-available memory monitor, but it will only read up to four active swapfiles before it stops registering more.

Finally, you may now use volumes (partition; disk) with a space character in the name, but due to a workaround required in the output code to fix a broken rm command, we suggest you avoid it until the beta period expires. Better disk names are:

My Hard Drive = OK
My_Hard_Drive = Better
my-HARD-drive = Better
MyHardDrive = Better

Please note that case does not matter; however, special characters such as '/' and '\' should also not be used; other special characters (e.g., ?, !, @, #, $, %, ^, *, (, ), +, =, etc.) have not been widely tested, so you should probably avoid them.

(Note to beta testers: if you're bored, please test this issue; the worst that should happen is your swapfile will revert to default; check error logs for confirmation-- thanks!)

How do I use SwapSwapVM?

The first thing you need to do is print out (at least) the page of this file containing the emergency instructions, just in case something goes wrong and you are unable to successfully restart your computer. While such incidents are highly unlikely, given the amount of care put into developing this application, anything can happen and you need to be prepared.

Now, don't let the above statement scare you off; SwapSwapVM is not going to wreck havoc on your system files, applications or data; it is merely going to make a change to the RC file (startup instructions), and this change can be easily undone if you have a problem, or if you just don't like the changes it makes.

If your computer crashes during or immediately after using SwapSwapVM, it is purely coincidental; SwapSwapVM does not write anything to any active memory space, .plist, file or even swapfile.

Getting Started

Once you've read, understood and printed these instructions, all you have to do is double-click the SwapSwapVM icon to launch the program -- but before running SwapSwapVM, you should save all open work and quit all other running applications (unless you are running in 'Simulation Mode'; see below).

Also, be sure not to remove SwapSwapVM from its folder, the one that also contains the file 'Read Me First!' (this document), or else the 'help' functions within the application will fail. (Future feature will resolve this.)

First you'll see the main screen:

• Press 'Reset Application' to gather information about your computer.

Next you will receive the description screen:

• The 'Status Message' pane will display your operating system version, the version of SwapSwapVM, and any possible initialization error messages (see Error Messages for more detailed explanations if needed).

• The 'Current Virtual Memory Settings' pane will display the current Virtual Memory swapfile directory path; if you have never altered your VM settings before it will read '/private/var/vm', which is located on your current Startup Volume; i.e., '[startup disk name]/private/var/vm'. This directory is normally invisible.

• Your current number of active swapfiles (i.e., 'swapfile0', 'swapfile1', etc.) is also displayed; it is assumed that the size of each is default at 80MB (76.2 actual). (Future versions of SwapSwapVM will report space used.)

• NOTE: Due to a current permissions bug, SwapSwapVM may not be able to return the current number of active swapfiles on certain volumes under certain conditions. A future release will deal with this issue.

• Any detected Virtual Memory errors may also be displayed here.

• Press 'Refresh Disk List' to get a list of possible Virtual Memory swapfile target disk candidates:

• A list of disks (volumes; partitions) will appear in the list pane under 'Choose a disk for Virtual Memory'.

• Use the scroll arrows if required to see all your possible disk choices.

• You must have more than one disk (volume; partition) available on your computer to see more than one choice.

• The amount of space used on the disk is expressed as a percentage value. You should avoid choosing a disk whose capacity is near or greater than 85% used; further, if the disk is not very large to begin with, even a disk that is only 50% used may not have sufficient free space to be a good swapfile host. Thus:

• The amount of free space on the disk is displayed in GB (Gigabytes), to the nearest 10MB (Megabytes) value, rounding down.

• E.G., in the example above, the Startup Disk, 'Macintosh HD', has 0.90GB, or 900MB, of available free space. If swapfile sizes are 80MB each, this disk has room for only eight (8) swapfiles before the disk becomes dangerously full. This would not be the best candidate for a Virtual Memory swapfile host.

• Whereas the disk 'swap' (also the Current Virtual Memory host in this example) has nearly twice the available space (1.78GB), and would be suitable for most people, the disk 'another swap volume' has a vast amount of free space (19.66GB), and would make an excellent Virtual Memory host choice.

• Be sure you also consider the speed, not just the size of the candidate. (see above)

• Space characters in volume names is now supported, but use disk names containing other special characters with caution! (See above)

• If you don't see the disk you want to use, it's because SwapSwapVM doesn't believe it will mount early enough in the boot process so as to be a reliable swap volume. If you like, you may now select the 'Show All Disks' option and then 'Refresh Disk List' to show all currently mounted volumes:

• CAUTION: Due to current limitations both in OS X 10.2.6 and older, as well as the current version of SwapSwapVM, it is possible to choose the wrong type of disk for use with Virtual Memory swapfiles. Although substantial error checking is included in the VM modification process, you could still end up with a disk you shouldn't have chosen.

• Rest assured, however, that even if you do, SwapSwapVM includes error handling that should prevent your inability to safely Restart your computer. That said:

• Do not select a Network drive. Though it is possible to use Virtual Memory over a Network, there are better ways to do it. If you know you need to do this, you almost assuredly know how to do it yourself. Enough said.

• Do not select a CD, CD-RW, DVD, DVD-R, DVD-RW or DVD-RAM disk, even if you can! Even if they are not locked, and are writable, they are too slow for Virtual Memory use!! Besides, they probably will not mount properly, and it would be too easy to remove the disk and cause VM settings to revert to default.

• Do not select a floppy disk, Zip disk, or Jaz disk, or any other type of removable media! Again, they are too slow and too easily removed!

• Use FireWire disks with caution! Even if they are faster or larger than your internal disk choices, SwapSwapVM uses a disk-candidate gathering routine that attempts to prevent choosing drives that, for one reason or another, have difficulty mounting early enough in the boot process so as to be used reliably as Virtual Memory targets.

• All FireWire drives suffer this issue, but the severity varies with each Mac model. Since SwapSwapVM is currently targeted to the masses, we opted to (currently) provide an override option that would allow someone to choose a disk that we have already excluded as being a risky option.

• FireWire drives may also be prone to go into their own Sleep Mode, causing severe System hangups that resemble complete freezes. If you use a FireWire disk and your computer appears to freeze up, wait several minutes before assuming it is really frozen. We have seen such cases where after three or more minutes, the computer comes back to life.

• One way you could work around this issue with the current beta is to "prove" to SwapSwapVM that your FireWire drive will consistently and reliably mount early enough in the Startup process; do this by choosing any appropriate volume *other* than your Startup Disk and executing SwapSwapVM changes to that volume (you may want to run simulation mode first and inspect the code output, if it would mean anything to you).

Once you have successfully Restarted using your new Virtual Memory target, relaunch SwapSwapVM to verify that Virtual Memory is now on said new volume; now see if your FireWire drive is an option. If so, Restart again, and see if it repeats. The number of times you can Restart and have your FireWire drive as an option in (the current version of) SwapSwapVM is a measure of the degree of reliability you can expect from your FireWire drive.

• If SwapSwapVM still refuses your FireWire drive, please let us know.

Once you select (highlight) your desired disk, press 'Select Disk' to continue:

• Your selected disk will now be confirmed in the 'New Virtual Memory Settings' pane.

• The new Virtual Memory swapfile directory path will appear directly below the disk choice.

• The default directory name is preset to 'SwapSwapVM'; this is in order to easily identify swapfiles on volumes other than the Startup Disk.

• You may choose to make the directory (not the host volume!) visible, or invisible. Default is visible.

• One of the most useful purposes for using SwapSwapVM is to help the user better manage and understand their own Virtual Memory swapfile usage and needs. By making the swapfile directory (folder) visible, the user can easily open and monitor the swapfiles that are created there. Unless that user has admin privileges, or the volume is set to 'Ignore Privileges on This Volume' (from the volume's 'Get Info' window), no harm, accidental or otherwise, can come from this.

• On the other hand, giving certain users (even visual only) access to that folder might be undesirable, so the option to make the directory invisible is also available.

• The possible file path would either then look like '/Volumes/YourSwapfileVolumeName/SwapSwapVM' or '/Volumes/YourSwapfileVolumeName/.SwapSwapVM', depending on your choice for visibility or invisibility.

• Future versions of SwapSwapVM will include the option to choose the directory name and depth; for now (unless you manually edit the output code in RC) you will have to live with the directory name and level provided.

Once you have determined your desired disk and visibility options, press 'Set New VM Path' to continue:

• You are now ready to finalize changes.

• If you are not satisfied with the settings, you may select (highlight) any other disk and press 'Select Disk' to start over.

• You may now elect to 'Reset VM and Restart' or 'Run Simulation'.

• Remember, if you actually execute changes to the RC file (Reset VM) , you must restart your computer for the changes to take effect. Unless you are running 'Simulation Mode', now would be a good time to stop and save all your open work if you haven't already done so!

• You may also elect to run SwapSwapVM in 'Simulation Mode', which will generate both a backup RC file and a simulated modified RC file for your inspection.

• If you have previously modified your RC file, either by manual use of pico or vi, et al, or you have used a utility to relocate the Virtual Memory swapfiles (e.g., Swap Cop, Swap Relocator, Xupport), it would be a good idea to run in 'Simulation Mode' once before you actually run it for real, so that any likely errors will not affect your current settings; also, there will be an easily-accessible RC backup file ( a copy of your current Virtual Memory and other RC settings) on your Desktop you can send to us for troubleshooting purposes.

Simulation Mode

• If you press 'Simulation Mode', a pair of files will be generated on the current user's Desktop for your inspection, and for potential troubleshooting issues.

• Simulation mode is now complete.

• A backup RC file, uniquely and conveniently named with the date and time, as well as a simulated RC file are waiting on your Desktop for inspection or use in troubleshooting:

• If this were the real thing, both of these files would be in your '/etc/rc' directory; one to replace your existing RC file, and another to serve as a backup, just in case something goes wrong.

Running SwapSwapVM for Real

• If you press 'Reset VM and Restart', you will initiate a process that will change your current Virtual Memory swapfile target disk settings.

• As SwapSwapVM is still currently a beta product, be sure you are prepared for the outcome!

• Just a friendly reminder to read the instructions, understand them fully, and have a printed set of instructions to recover from any unforeseen errors. If you don't print the emergency sheet, and you end up being unable to Restart your computer, and you don't know how to fix it, don't come crying to us!

For Advanced Users Only (skip to the next section only if none of the below applies to you):

• Have you (or someone else) ever modified your current '/etc/rc' file? If you don't know, or don't understand the question, the answer is probably 'No'. This is typically a safe answer, as SwapSwapVM includes enough error handling to prevent severe issues even if it has been modified previously; however:

• If you have used a utility such as Swap Cop, Swap Relocator, or Xupport to modify your Virtual Memory swapfile settings, be sure to run 'Simulation Mode' at least once before the real thing.

• If you (or someone else) has ever manually edited the current 'etc/rc' file, be sure to run 'Simulation Mode' at least once before the real thing.

• This is just a warning to let you check the outcome of running SwapSwapVM before your commit to the changes.

• If you have run Swap Relocator 1.0 in the past, SwapSwapVM changes to RC will take place, but will not remain active unless you disable the Swap Relocator setting in '/etc/hostconfig' file (see its Read Me for instructions).

* If you have manually edited the 'etc/rc' file by moving the Virtual Memory section to the end of the file, SwapSwapVM cannot currently alter these settings. Run 'simulation mode' to test the ability to execute changes without error. Otherwise, restore your original RC file from your backup (you did make a backup before editing the RC file, didn't you?) prior to such modifications.

• PLEASE NOTE: The current version of SwapSwapVM will overwrite any modifications made to the swapfile size settings and restore them to default. If you wish to retain such settings, don't use SwapSwapVM, or go back and change them again after SwapSwapVM makes its settings.

• If SwapSwapVM refuses to "see" your FireWire drive, you can manually override it by editing RC to reflect your FireWire volume name (must not contains spaces or other special characters!).

In Terminal, type:

sudo pico /etc/rc

.. enter your admin password, press 'Return', then press 'Control-W' (for 'Where is') and type:

swapVOL=

... Then press 'Return'; now edit the section of that line that includes your current VM target disk name to reflect your FireWire disk name; be sure it remains within the quotes and you do not remove the '/Volumes/' prefix!

E.G.

swapVOL="/Volumes/MyFireWireDiskName"

Now press 'Control-X' (for 'Exit'); Press 'Return'; Press 'Y' (for 'Yes'); Press 'Return'; Press 'Return' a second time (to confirm overwriting the existing file).

Now, you can exit the Terminal session and Restart to test your changes as above. If your computer fails to Restart properly (which will only happen if you break the code!), use the instructions on the last pages of this file to restore your backup RC.

• The good news is that even if you are able to choose your FireWire drive (manually or automatically), and it occasionally fails to mount in time, SwapSwapVM includes error handling code to put Virtual Memory back on your Startup Volume. The only problem is that, unless you either run SwapSwapVM to get the 'Current VM Settings' or read the 'SwapSwapVM.log' file after each Restart, you will not know if an error has occurred.

• With enough support and interest, such features as expanded support for FireWire drives will be added in future releases.

For ALL Users:

Unless you are logged in as 'root' user, you will see the following:

• You may 'Authenticate' only if you have administrator privileges.

• Select 'Run Simulation' on the main application window if you do not have administrator privileges.

• SwapSwapVM will only make changes to the real RC file if you have proper authorization.

• A pair of files will be generated (later in the process) in the '/etc/' directory. One will be a modified RC file with your new Virtual Memory swapfile settings; the other will be a date-stamped backup file, easily identifiable for quick restoration in the event of an emergency or a desire to simply restore previous settings.

• PLEASE NOTE: This is your last chance to bail out (barring any processing errors) before the process is completed!

If SwapSwapVM does not encounter any errors, you will see:

• The 'volume named:' portion of the 'Status Message' pane will reflect the name of your new Virtual Memory swapfile host disk.

• CRITICAL WARNING: If you ever remove or rename the disk (volume; partition) that you selected for SwapSwapVM Virtual Memory swapfile settings, Virtual Memory swapfiles will revert to the (invisible) default path at '/private/var/vm' on the Startup Volume.

• In such events, SwapSwapVM will generate error messages on each subsequent Startup (visible only in Verbose Mode), and write said errors to the SwapSwapVM.log file. No other obvious warnings will be evident to the user.

• A reminder in the 'Status Message' pane appears indicating that the current RC file is now modified, and that a date-stamped backup file is also there for quick access, should you need it.

• That's it. Just let SwapSwapVM Restart the computer, and enjoy your new settings.

• IMPORTANT: Once your computer has Restarted, you should run SwapSwapVM again to get your 'Current VM Settings' to make sure your new Virtual Memory swapfile settings are in effect.

Resetting Virtual Memory to Default Settings (Startup Disk Only)

If you decide you no longer want SwapSwapVM to redirect your Virtual Memory swapfiles to another volume, you can easily restore your default settings in one of two ways:

• You may manually restore your '/etc/rc' file from the backup file originally made by SwapSwapVM, also located in your '/etc/' directory. It will be named 'rc.swapswap.backup.[datestamp]', where '[datestamp]' is the date and time the backup file was made.

• If you find more than one SwapSwapVM-generated backup file, the oldest-dated file will be a copy of your original RC file.

• Future versions of SwapSwapVM will offer a restoration feature; for now, you will have to use Terminal or the GUI (with administrator privileges) to restore to your original Virtual Memory settings.

• To restore the file manually, simply rename the appropriate file (e.g.: rc.swapswap.backup.030518) to simply 'rc' (without the quotes). Please note: You will first have to rename the existing 'rc' file to something else.

• Once done, Restart your computer to restore your orginal RC settings. PLEASE NOTE: Any errors in your original RC file generated by other utilites will be restored along with eliminating SSVM changes! Be sure your original RC file was in good shape! Future versions of SSVM will add the ability to install a "stock" RC file identical to one generated by a clean install of OS X.

• However, if you do not care about YOUR original Virtual Memory settings, or are concerned that your orignal RC file is corrupted, and are content to use Apple-blessed settings (nearly identical to the ones that were installed with OS X, except for a notation that SSVM did the job), you may use SwapSwapVM to select your Startup Disk to restore:

• Simply select (highlight) your Startup Disk; press 'Select Disk'; press 'Set New VM Path'; press 'Reset VM and Restart; then authorize as above.

• Once completed, your computer will Restart.

• That's it. Just let SwapSwapVM Restart the computer, and enjoy your default settings.

• IMPORTANT: Once your computer has Restarted, you should run SwapSwapVM again to get your 'Current VM Settings' to make sure your default Virtual Memory swapfile settings are in effect.

• IMPORTANT: Because you have opted to remove SwapSwapVM settings in your RC file, you will be left with AT LEAST ONE (1) UNUSED SWAPFILE on your last Virtual Memory host disk that you will have to manually remove.

• Inactive swapfiles will be located at:

'/Volumes/[old disk host name]/SwapSwapVM/' (visible)

or

'/Volumes/[old disk host name]/.SwapSwapVM/' (invisible)

... where '[old disk host name]' is the name of the last disk used by SwapSwapVM for Virtual Memory settings.

• A future version of SwapSwapVM will find and remove such files.

Error Messages while running SwapSwapVM

"SwapSwapVM v x.x.x has not been qualified yet for this version. Check with the author for a newer version."

In order to prevent unknown issues with unreleased, and therefore untested versions of the Mac OS, SSVM will not run on any version it has not been fully tested with. Check the website for the latest version and the OS version it has been tested to run with.

"ERROR: OS version unknown! If you are sure you are running Mac OS X 10.2.0 through 10.2.4 then you may proceed with caution! Please report this exact error message to the developer."

There are rare instances where SwapSwapVM is unable to determine the version of your current Operating System. Previous versions disabled SwapSwapVM; this version will allow you to proceed without knowing your OS version. Be sure you know what it is, and that it's compatible.

• "This is current VM setting! No need to change!"

This error will only occur if you attempt to duplicate the current Virtual Memory settings. If you have used another utility to create these settings, and wish to install SwapSwapVM code for its superior error handling abilities, you must first select another (any other) appropriate volume, reset Virtual Memory to it; Restart, then you may choose your originally desired disk.

• "ERROR! You failed to choose a disk! You must select (highlight) a disk in the list BEFORE you press 'Select Disk'."

Use your mouse cursor (the little black arrow) to select a disk in the upper left list pane under 'Choose VM Target Disk:' by pointing to the desired disk name and clicking your mouse so that it is highlighted BEFORE you press the 'Select Disk' button.

If your desired disk is not reflected by the 'New Virtual Memory Settings' pane, even though you are sure you selected the correct disk, press 'Refresh Disk List' and try again.

• "ERROR: Help file 'Read Me First!' is missing! If you require assistance, select 'Help' from the Menubar above instead."

The file (this file) 'Read Me First!' has somehow become missing; either because you have removed it, or the SwapSwapVM application from the original folder. Quit SwapSwapVM and place the 'Read Me First!' file in the same folder as the SwapSwapVM application to clear this error.

• "ERROR: SwapSwapVM requires file '/sbin/autodiskmount' in order to run! This file is missing; reinstall '/sbin/autodiskmount' to use SwapSwapVM settings!"

SwapSwapVM relies on the process file 'autodiskmount', which, by default, is located in the (invisible) /sbin/' directory. If you have moved this file, or it has become damaged in any way, SwapSwapVM cannot mount your desired Virtual Memory target disk in time for the swapfiles to be created during Startup.

If this file is not present, SwapSwapVM will not allow you to make any changes.

• "ERROR: Unable to determine if '/sbin/autodiskmount' exists! Proceed with caution!"

If this file is moved or damaged after using SwapSwapVM, Virtual Memory will automatically revert to the default directory ('/private/var/vm') on the Startup Volume. Errors will generate visibly in Verbose Mode and be written to the 'SwapSwapVM.log' file located in '/Library/Logs/'.

• "ERROR: Unable to determine number of swapfiles at /private/var/vm"

There may be unused or active swapfiles present in the default directory on the Startup Volume, but SwapSwapVM can't tell how many. Shutdown, then Restart your computer and run SwapSwapVM again to see if the error clears.

• "ERROR: "(number) unused swapfiles found at /private/var/vm!"

This error most often is seen when the user has previously modified the Virtual Memory settings (either manually or with a third party utility) and those unused swapfiles were never removed. Using SwapSwapVM to reset your Virtual Memory settings, and then Restarting the computer will generally clear this error and remove any unused swapfiles (at that location).

• "The administrator password is incorrect or missing."

You entered the incorrect administrator password for the current user.

• "Unable to determine current VM path; please try again."

SwapSwapVM could not determine the current Virtual Memory swapfile directory. Select 'Reset Application' to try again. If the issue persists, please report the exact error to the developer.

• "ERROR: Unable to determine current VM path; unable to proceed; see help file."

SwapSwapVM uses 'ps' and grep to determine the current swap volume. If it cannot find the current path, its settings in RC would fail to remove old swapfiles. Not a huge issue, but one worth preventing. Try restarting your computer to clear the error. If the issue persists, please report the exact error to the developer.

• "Current swapfile count unknown; see help file."

In some instances, SwapSwapVM is unable to work around permissions issues to count the current number of active swapfiles. This is just an annoyance, and will not affect the safety of new or existing SwapSwapVM settings. Use another utility to determine active swapfile count.

• "Current swapfile count: [number] (code: -1728)

This is just a flag to let us know when one of our current workarounds for determining swapfile count is being used. The code is harmless and will not effect your settings in any way.

• "Unable to get list of currently mounted local disks; please try again."

SwapSwapVM is unable to get a list of potential disks (volumes; partitions) for you to choose from. Select 'Reset Application' to try again. If the issue persists, please report the exact error to the developer.

• "ERROR: Unable to parse disks; no harm done; no settings changed."

SwapSwapVM is having trouble making sense of the list of currently mounted volumes. This may be due to the use of special characters in the name, or using an OS X version other than English. Select 'Reset Application' to try again; else Restart the computer and start over. If the issue persists, please report the exact error to the developer.

• "Unable to parse disk path; no harm done; no settings changed."

SwapSwapVM is having trouble getting the name of potential target disks. This may be due to the use of special characters in the name, or using an OS X version other than English. Select 'Reset Application' to try again; else Restart the computer and start over. If the issue persists, please report the exact error to the developer.

• "VM is already using default. Unless you are attempting to correct an error in RC, you should quit."

SwapSwapVM has determined that Virtual Memory swapfiles are currently active on the Startup Volume; there is no need to make a change unless you are trying to correct an error; if you think RC is designed to use another volume, and you wish to overwrite the current RC file with default (Apple-blessed) settings, proceed.

• "This disk is more than 85% full ("xx%" full); you should not fill any Mac OS volume beyond that limit."

It is a very bad idea to fill any Mac OS HFS+ disk to an amount greater than 85% of its capacity, whether it is with swapfiles or not. Select 'override' only if you know what you are doing, and are prepared to do additional disk maintenance. Buy a fresh copy of DiskWarrior, and use it frequently!

• "This disk is 100% full, and would not be suitable for a swap directory. It is also possible that it is a locked or removable volume such as a CD or DVD,"

Dude, do we really have to explain this one? OK, fine; if a disk is 100% full, then there is no room to create an 80MB swapfile, let alone a bunch of them.

•"ERROR: Unable to read original RC!" (with error number & additional text)

There was a problem reading your current RC file. Try Restarting your computer and then running SwapSwapVM again. If the error occurs more than twice, please report the exact error to the developer.

• "ERROR: Unable to write a backup of your current RC file to the Desktop!" (with error number & additional text)
• "ERROR: Unable to write a backup of your current RC file to /etc/!" (with error number & additional text)

There was a problem when trying to write your backup RC file. Try Restarting your computer and then running SwapSwapVM again. If the error occurs more than twice, please report the exact error to the developer.

• "ERROR: Unable to find current Virtual Memory string in current RC file!" (with error number & additional text)

SwapSwapVM is unable to find the original Virtual Memory string in '/etc/rc' as it expects to find it. This will typically occur only if you (or someone else) has heavily modified the Virtual Memory settings in the RC file; the most common issue is when someone has moved the whole VM section to the end of the file. Future versions of SwapSwapVM might be able to fix this problem; for now, you can either:

-- restore your RC file from a backup without such changes
-- manually edit your RC file so the original VM text is where it belongs
-- use the SwapSwapVM code sample from this file manually

If you're sure you didn't mess around in RC previously, copy the text from the 'simulation mode' rc.swapswap.backup.[datestamp] file to an email and send it to the developer with a note about the error code.

• "ERROR: Unable to set replacement Virtual Memory string." (with error number & additional text)

This one is rare. Try resetting the application; else restart the computer and try again. If the error occurs more than twice, please report the exact error to the developer.

• "ERROR: Unable to replace Virtual Memory string in existing RC file." (with error number & additional text)

There was a problem editing your current RC file. Try Restarting your computer and then running SwapSwapVM again. If the error occurs more than twice, please report the exact error to the developer.

• "ERROR: Unable to write modified RC file to the Desktop." (with error number & additional text)
• "ERROR: Unable to write modified RC file to /etc/." (with error number & additional text)

There was a problem writing your new RC file. SwapSwapVM failed to write a simulated RC file on your Desktop or in your /etc/ directory, depending on which mode you are attempting. Try Restarting your computer and then running SwapSwapVM again. If the error occurs more than twice, please report the exact error to the developer.

• "Unable to Restart; application (probably an AppleScript Editor) won't quit; please select Restart from the Apple Menu."

Self-explanatory. We're working on a new method to engage Restart. We may also remove the Restart procedure altogether, and trust the user to do so.

• Other errors while running SwapSwapVM

Try Restarting your computer and then running SwapSwapVM again. If the error reoccurs at the same place, write down the exact text of the error message; indicate the last dialog box you saw before the error, and report it to the developer.

Possible Future Additions to SwapSwapVM

• Ability to set swapfile sizes.
• Ability to turn Virtual Memory off altogether (for troubleshooting purposes).
• AppleScript Studio interface (allows for metal appearance and smaller application size).
• Preference Pane interface.
• More free space and swapfile size calculations.
• Better disk selection to avoid improper disk choices.
• Better support for FireWire (and other) drives for advanced users.
• Ability to remove all inactive swapfiles on all mounted volumes.
• Ability to restore previous or original (or other) RC files automatically.

If enough people ask for it:

• Ability to wipe out Swap Relocator 1.0 settings
• Ability to fix problems with App_Profile settings caused by Xupport 1.2.4 and earlier.
• Ability to modify RC files where the user has moved the VM section to the end of the RC file.
• Ability to restore an Apple-blessed, purely stock RC file
• Ability for user-selected VM directory name and depth.

Version History

New for SwapSwapVM 0.9.9b9
• Added a reliable workround for current VM file path data string; fixes RC output corruption.

New for SwapSwapVM 0.9.9b8
• Qualified for use with OS X 10.2.5 and 10.2.6
• New icon by Elroy.
• Added a 'Show All Disks' feature to allow disks (such as FireWire drives) thought by SSVM to be "unsafe". Use this feature with caution (see Read Me file).
• Fixed a bug where Current VM Stats were unknown on volumes with spaces in names
• Fixed a behavior where a new target disk would not be generated in RC output if another disk was previously chosen in Simulation Mode
• Fixed a slew of bugs generated during data gathering introduced by OS X 10.2.5 and 10.2.6.
• Added additional error handling and logging in RC output.

New for SwapSwapVM 0.9.9b4
• Qualified for use with OS X 10.2.4
• Added better error handling for 'Can't get current VM'
• Added better error handling for 'Can't parse disks'
• Added still more improved error handling everywhere else
• Removed all modal dialogs
• Improved error information -- less ominous and less arcane!
• Fixed a launch error if logged under root
• Updated Documentation
• More


New in SwapSwapVM 0.9.9b2
• New Aqua application interface; made with Smile 2.5.1
• Ability to use disks with space characters in the name
• Yet more error handling.
• Faster, cleaner code.
• Fixed a bug finding the help files preventing SSVM from running
• Fixed a bug resetting default swap in some cases
• Added error handling and checking for autodiskmount
• Added a workaround for broken RM command when path includes spaces; issue prevented old swapfiles from being removed.
• Updated documentation

0.9.8b12 fixed handler code error; optimized more code; updated documentation
0.9.8b11 changed default vm error output handlers
0.9.8b10 Initial public beta released.
0.9.8b9 added 'Read Me First!' file
[a bunch of versions with a bunch of stuff added and fixed]
0.1.0b initial code written; features planned

Here is a sample of the code SwapSwapVM will install:

(You can ignore this section of you don't really care or understand it)


##
# Start the virtual memory system.
##

# Virtual Memory Modified by SwapSwapVM v0.9.9b1 on Wednesday, February 12, 2003 09:22:49 PM

Consolemessage "Starting Virtual Memory"

swapVOL="/Volumes/swap"
swapDIRn="/SwapSwapVM"
swapDEF="/private/var/vm"
swapOLD="/Volumes/resources too/.SwapSwapVM"
ssLOG="/Library/Logs/SwapSwapVM.log"

Consolemessage "Begin autodiskmount..."

if [ -f /sbin/autodiskmount ]; then
/sbin/autodiskmount
else
echo "ERROR: /sbin/autodiskmount is missing. reverting to default swap..."
echo "`date` - ERROR: /sbin/autodiskmount is missing. Reverting to default swap." >> "$ssLOG"
ConsoleMessage "Cannot find /sbin/autodiskmount. Reverting to default, see /Library/Logs/SwapSwapVM.log"
swapVOL="${swapDEF}"
swapDIRn=""
fi



if [ -d "${swapOLD}" ]; then
rm -rf /Volumes/resources\ too/.SwapSwapVM/swap*
echo "removing old swapfiles from ${swapOLD}"
echo "`date` - Old swapfiles removed from ${swapOLD}" >> "$ssLOG"
fi

if [ ! -d "${swapVOL}" ]; then
ConsoleMessage "Cannot find user specified swap volume. Reverting to default, see /Library/Logs/SwapSwapVM.log"
echo "`date` - ERROR: cannot find user specified Swap Volume '${swapVOL}' for SwapSwapVM; volume or disk may have been removed or renamed; Reverting to default at ${swapDEF}; run SwapSwapVM again to correct error; For more information go to http://www.sciencequest.org/jump/swapswapvm.html" >> "$ssLOG"
swapdir="${swapDEF}"
ssERRORtxt="${swapdir}/swap_READ_ME_Virtual_Memory_ERROR.txt"
else
echo "Set swapdir to ${swapVOL}"
swapdir="${swapVOL}${swapDIRn}"
echo "`date` - Setting Virtual Memory path to ${swapdir}" >> "$ssLOG"
fi

if [ "${netboot}" = "1" ]; then
sh /etc/rc.netboot setup_vm "${swapdir}"
fi

# Make sure the swapfile directory exists
if [ ! -d "${swapdir}" ]; then
ConsoleMessage "Creating default swap directory"
mount -uw /
mkdir -p -m 755 "${swapdir}"
chown root:wheel "${swapdir}"
ssABOUTtxt="${swapdir}/About_This_Folder.txt"
echo "`Date` - If the folder containing this file contains files called 'swapfile0', 'swapfile1', etc. DO NOT DELETE THIS FOLDER. If this folder only contains this file, you may delete the folder. To test if this is your active VM target folder, delete this file, Restart your computer; if this file reappears, this is the active VM directory. File generated by SwapSwapVM v0.9.9b1. For more information go to http://www.sciencequest.org/jump/swapswapvm.html" >> "$ssABOUTtxt"
else
rm -rf ${swapdir}/swap*
fi

if [ -f "${swapDEF}/swapfile0" ]; then
echo "ERROR: see ${ssLOG}"
echo "ERROR: Removing errant swapfiles from ${swapDEF}; last system session had incorrect VM path settings or desired VM disk was removed or renamed; check VM settings." >> "$ssLOG"
rm -rf ${swapDEF}/swapfile*
fi


if [ ! -d "${swapVOL}" ]; then
echo "`Date` - Your Virtual Memory settings are (or were) incorrect!; the designated volume ${swapVOL} cannot be found; it may have been removed or renamed; to confirm, delete this file, Restart computer, and check for this file again; if it reappears, run SwapSwapVM to correct. For more information go to http://www.sciencequest.org/jump/swapswapvm.html; File generated by v0.9.9b1" >> "$ssERRORtxt"
fi

dynamic_pager -H 40000000 -L 160000000 -S 80000000 -F "${swapdir}/swapfile"

# End SwapSwapVM Modification on Wednesday, February 12, 2003 09:22:49 PM
# For more information go to http://www.sciencequest.org/jump/swapswapvm.html

What to do if your computer won't Startup

It is EXTREMELY UNLIKELY that anything SwapSwapVM does will cause your computer to fail to Startup sucessfully. If, after using SwapSwapVM, your computer fails to Startup, it is important to determine when to determine why you're having a problem, as it likely has nothing to do with SwapSwapVM at all.

• If your computer reaches the blue screen before hanging up, it has nothing to do with SwapSwapVM; the Virtual Memory process was done many, many steps before this stage. Just be patient; every once in awhile OS X simply needs more time to make things work. If, after five or more minutes, your computer fails to finish the Startup process, press the reset button.

• If your computer begins with the gray screen and Apple logo; starts its spinning wheel and then stops, leaving you with:

sh-2.05a#

...or something similar in the upper left corner (very small; look carefully).

type the following:

reboot

... and then press 'Return'.

Now, immediately after the Startup sound, but before the Apple logo appears, press and hold down the keys 'Command-V'; this will Startup your computer in Verbose Mode. You will see your normally gray screen turn to black and start spewing out text; then you may release the keys.

Watch the text very carefully for the following messages:

• Starting Virtual Memory
• Begin autodiskmount...
• Removing old swapfiles from [path]
• Launch dynamic_pager at [path]
• Virtual Memory by SwapSwapVM successful
• If your computer fails to finish starting up from this point, it's not SSVM's fault

If your computer stops for more than a minute or two before you see the last item, then there is indeed a problem with SwapSwapVM settings. That doesn't mean it's SwapSwapVM's fault; e.g., you may have chosen the wrong type of disk for use with Virtual Memory.

If, however, you see the last message in the above list, then your computer not starting has nothing to do with SwapSwapVM settings. You can verify this by reading the log file at /Library/Logs/SwapSwapVM.log

If your computer freezes for more than two minutes and leaves you with:

sh-2.05a#

... type:

pico /library/logs/swapswapvm.log

.. you can now read the log data to verify that it does, or does not have any errors reported by SwapSwapVM from this Startup session (note the date and time).

In the unlikely event that something does go wrong with SwapSwapVM settings, such as you chose a disk that is there, but cannot be written to, or the new RC file is somehow corrupted when written, again, you will typically see your Mac begin its normal Startup; you'll see the gray Apple logo (OS X 10.2.x Jaguar); the timer wheel will spin for a minute or so, then stop; up in the upper right hand corner of the screen, you'll see a tiny line of text that says:

sh-2.05a#

...or something similar.

type the following:

cd /etc

... and press the 'Return' key (that's cd-space-/etc); It should return:

sh-2.05a#

type:

ls

... and press the 'Return' key (that's letters 'LS' in lower case); you should now see two or three columns of text; look for a file there named 'rc'.

Now type:

mv rc rc-bad

...and press the 'Return' key (that's mv-space-rc-space-rc-dash-bad); it should return the command prompt again:

sh-2.05a#

...now look for a file called rc.swapswap.backup.[datestamp], where [datestamp] is is probably today's date & time of when you ran SwapSwapVM.

For example: rc.swapswapvm.backup.03Feb01-10.45.29AM

Now type:

mv rc.swapswap.backup.[datestamp] rc

... and press the 'Return' key (that's mv-space-rc.swapswap.backup.[datestamp]-space-rc, where [datestamp] = the date string on the end of the most recent backup file.)

For example: mv rc.swapswap.backup.03Feb01-10.45.29AM rc

....now you should see one last command prompt:

sh-2.05a#

...where you type:

reboot

...and press the 'Return' key. Your computer will now Restart, and should run as well as it did before using SwapSwapVM.

In order to determine what happened, please send a copy of '/etc/rc-bad' to the developer with a description of the problem.

http://www.sciencequest.org

SwapSwapVM@sciencequest.org